🏪 Merchant Initiated Transactions

What is a Merchant Initiated Transaction?

A Merchant Initiated Transaction (MIT) uses payment credentials previously authorized by a customer to process payments without their active participation at the time of charge. This enables business models where charges occur based on usage, events, or merchant-determined timing.

📘 Key Difference from Card on File

Unlike Card on File transactions where the customer actively participates in each purchase, MIT transactions are initiated by the merchant without the customer being present or actively involved.

Key Characteristics

• No Customer Participation: Charges are processed without the customer actively initiating payment
• Prior Authorization Required: Customer must have previously authorized their card for MIT use
• Merchant-Driven Timing: You control when charges occur based on your business logic
• Unscheduled Charges: Ideal for variable amounts and timing (usage-based, threshold triggers, etc.)

MIT Compliance & Requirements

Card networks require specific handling for Merchant Initiated Transactions to protect consumers and ensure proper transaction categorization.

Compliance Requirements

Critical Compliance Steps

1. Obtain explicit consent for storing credentials and processing future MIT charges
2. Clearly disclose how, when, and why their card will be charged
3. Provide terms that explain MIT usage (e.g., usage-based billing terms)
4. Maintain records of customer consent for audit purposes
5. Notify customers before each transaction commences

Coinflow handles the technical compliance, but you must obtain and document customer consent.

Use Cases for MIT

Usage-Based Billing

Charge customers based on consumption (API calls, storage, bandwidth, etc.)

Account Top-Ups

Automatically add funds when balance falls below threshold

Post-Service Charges

Bill for services after completion (ride-sharing, delivery tips, etc.)

Delayed Fulfillment

Charge when items ship or services are delivered

How It Works

Customer Authorizes Card

Customer completes an initial purchase or authorizes their card via a zero auth transaction and consents to future MIT charges on your platform.

Coinflow Stores MIT Credentials

The card details and MIT authorization reference are securely stored in Coinflow’s PCI-compliant vault.

You Trigger the Charge

When your business logic determines a charge is needed (usage threshold, billing cycle, etc.), you call the MIT endpoint.

Payment is Processed

Coinflow processes the payment using the stored credentials without requiring customer interaction.

Card on File vs. Subscriptions vs. Merchant Initiated Transactions

Understanding the differences between payment types helps ensure compliance and proper implementation:

💡 Need Fixed Recurring Payments?

If you need automated payments on a fixed schedule (monthly, weekly, etc.), check out our Subscriptions Overview documentation.

Implementation Guide

Implementing Merchant Initiated Transactions is a two-step process:

1. Initial Authorization - Store the customer’s card with MIT authorization
2. Subsequent Charges - Process MIT payments as needed

Step 1: Authorize Card for MIT Use

One approach is to perform a zero authorization on the card to validate and store the card for MIT use. This authorizes the card for $0.00, establishing the credentials without charging the customer.

POST /api/checkout/zero-authorization/{merchantId}

Request Body:

{
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cvv": "123"
  }
}

Or use a previously tokenized card:

{
  "token": "4111114324324111_bt"
}

Save the Payment ID

After a successful Zero Authorization, save the paymentId from the response. You’ll use this as the originalPaymentId for subsequent MIT charges.

Alternative: Initial Purchase

You can also use a regular card payment as the original authorization. Any successful card transaction with CVV verification can be used as the originalPaymentId for MIT. This is useful when the customer is making an initial purchase and you want to enable future MIT charges.

Using a Saved Token:

POST /api/checkout/card/{merchantId}

{
  "subtotal": {
    "cents": 1500,
    "currency": "USD"
  },
  "token": "4111114324324111_bt"
}

Using a New Card:

{
  "subtotal": {
    "cents": 1500,
    "currency": "USD"
  },
  "card": {
    "number": "4111111111111111",
    "expiryMonth": "12",
    "expiryYear": "2025",
    "cvv": "123"
  }
}

Response:

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000"
}

Save the Payment ID

Just like with Zero Authorization, save the paymentId from the checkout response. You’ll use this as the originalPaymentId for subsequent MIT charges. The initial purchase amount also establishes the baseline for maximum MIT charge calculations (based on your maxMultiple setting).

Step 2: Process Merchant Initiated Transactions

When your business logic determines a charge is needed, call the MIT endpoint with the original payment ID.

POST /api/checkout/merchant-initiated-transaction

View MIT API Reference

Request Parameters:

Advanced: On-network settlement parameters

These optional parameters only apply to merchants configured for on-network settlement. Reach out to your Coinflow integration representative if you need them.

Example Request:

{
  "subtotal": {
    "cents": 2500,
    "currency": "USD"
  },
  "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000",
  "settlementType": "Bank"
}

Step 3: Handle the Response

A successful MIT returns the new payment ID:

{
  "paymentId": "650e8400-e29b-41d4-a716-446655440001"
}

Complete Example

Option 1: Zero Authorization Flow

Here’s a complete example showing Zero Authorization followed by an MIT charge:

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/zero-authorization/your-merchant-id \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-id: customer-123' \
  --data '{
    "token": "4111114324324111_bt"
  }'

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000"
}

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/merchant-initiated-transaction \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Authorization: your-merchant-api-key' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 5000,
      "currency": "USD"
    },
    "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000",
    "settlementType": "Bank"
  }'

{
  "paymentId": "650e8400-e29b-41d4-a716-446655440001"
}

Option 2: Initial Purchase Flow

Here’s a complete example showing an initial card purchase followed by an MIT charge:

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/card/your-merchant-id \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 2500,
      "currency": "USD"
    },
    "token": "4111114324324111_bt"
  }'

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/card/your-merchant-id \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 2500,
      "currency": "USD"
    },
    "card": {
      "number": "4111111111111111",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "cvv": "123"
    }
  }'

{
  "paymentId": "550e8400-e29b-41d4-a716-446655440000"
}

curl --request POST \
  --url https://api-sandbox.coinflow.cash/api/checkout/merchant-initiated-transaction \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'Authorization: your-merchant-api-key' \
  --header 'x-user-id: customer-123' \
  --data '{
    "subtotal": {
      "cents": 5000,
      "currency": "USD"
    },
    "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000",
    "settlementType": "Bank"
  }'

{
  "paymentId": "650e8400-e29b-41d4-a716-446655440001"
}

Maximum MIT Amount

The maximum amount allowed for a MIT is determined by the maximum amount a customer has spent in a customer initiated transaction (CIT) where the customer provided the CVV.

However, default maximum amounts apply to customers without any transaction history but who have authorized their card via zero auth. Your Coinflow integration representative will configure this default for you.

Merchant Configuration Settings

Merchant Initiated Transactions include configurable settings that control how and when stored credentials can be used. These settings help manage security, fraud prevention, and compliance.

Configuration Required

MIT functionality must be enabled on your merchant account before you can process MIT payments. Contact your Coinflow integration representative to configure these settings.

Available Configuration Options

Your Coinflow integration team will configure the following MIT settings for your merchant account:

Velocity Controls:

• maxCount - Maximum number of MIT payments allowed within a time period
• period - Time window in seconds for the maxCount limit (e.g., 86400 for 24 hours)

For example, if I have a period of 90 seconds and a max count of 5, then I can only process 5 transactions for a given customer using a given originalPaymentId in 90 seconds. If I attempt more, then I will receive a 429 error.

Payment Limits:

• maxMultiple - Maximum multiplier for MIT transaction amounts compared to the maximum historical payment amount
• maxZeroAuthAmount - Default maximum amount for MIT when customer has no transaction history
• maxAmountLookback - Time window to look back for maximum payment amount calculation

Examples

1. If a customer has spent in CVV verified payments, $10.00, $6.00, $12.00, and $40.00 and all of these payments fall in the maxAmountLookback time frame, then $40.00 will be used as the base maximum amount. This value will then be multiplied by the maxMultiple to determine the maximum amount that can be charged in a MIT.
2. Let’s say a customer just signed up for your usage-billing based platform, and when they add a card you perform a zero authorization on that card where the user provides the CVV. Now you try to perform a MIT charging this user. The maximum amount they can be charged is the maxZeroAuthAmount multiplied by the maxMultiple.

Time-Based Restrictions:

• expiration - Time window in seconds during which an originalPaymentId can be used for MIT

For example, if the expiration is 2 weeks, and the original payment (from originalPaymentId) is older than 2 weeks, then I can no longer use this as the originalPaymentId for a MIT. I must retrieve a newer CIT. Example flows could be a usage based billing platform where now I prompt the user to complete a payment manually where they enter in their CVV and then use that paymentId for subsequent MITs, or simply ask the customer to reauthorize their card with a zero authorization.

Example Configuration

"enabled": true,
"maxCount": 5,
"period": 86400,
"maxMultiple": 3,
"expiration": 2592000,
"maxZeroAuthAmount": { "cents": 2000 },
"maxAmountLookback": 2592000

This configuration means:

• ✅ MIT is enabled
• ✅ Maximum 5 MIT payments per 24 hours per original authorization
• ✅ MIT payments can be up to 3× the customer’s maximum historical payment
• ✅ Original authorizations can be used for 30 days
• ✅ Zero Authorization allows up to $20.00 × multiplier for MIT charges

Error Handling

Understanding and properly handling MIT errors is critical for a smooth implementation.

Common Error Codes

403 Forbidden - MIT Not Enabled

Error Message:

Merchant Initiated Transaction not enabled. Please contact your integrations representative.

Cause: MIT functionality is not enabled on your merchant account.

Resolution:

• Contact your Coinflow integration representative to enable MIT
• Once enabled, configure the appropriate settings for your use case

400 Bad Request - Mobile Wallet Payments

Error Message:

Cannot perform card on file operations for mobile wallet payments

Cause: You’re attempting to use a mobile wallet payment (Apple Pay, Google Pay) as the original authorization for MIT.

Resolution:

• Mobile wallet payments cannot be used as MIT references
• Use a regular card payment as the initial authorization
• For mobile wallet payments, customers must authenticate each time (to be rectified soon)

400 Bad Request - Invalid Original Payment

Error Message:

Cannot perform card on file operations for a originalPaymentId which is a card on file transaction,
please pass the originalPaymentId which processed with the CVV Verification

Cause: You’re attempting to use an MIT or Card on File payment as the original authorization.

Resolution:

• Only use the initial CVV-verified payment as the originalPaymentId
• Do not chain MIT transactions
• Always reference back to the original CVV-verified payment

429 Too Many Requests - Maximum Payments Reached

Error Message:

Max number of Card-on-File payments reached. (X payments in Y seconds)

Cause: The customer has exceeded the maximum number of MIT payments allowed within the configured time period.

What This Means:

• Too many MIT charges have been processed against this authorization
• This is a security measure to prevent abuse
• Based on your merchant’s maxCount and period settings

Resolution Options:

1. Option A: Wait for Period Reset

   • Wait for the current period to expire
   • The counter resets after the configured period

2. Option B: New Authorization

   • Have the customer re-authorize their card
   • Process a new Zero Authorization or card payment with CVV
   • Use this new payment ID for future MIT charges

410 Gone - Original Payment Expired

Error Message:

This original payment can no longer be used as a card-on-file reference because it has exceeded
the allowed X-minute reference window.

Cause: Too much time has passed since the original authorization. The reference has expired based on your merchant’s expiration setting.

Resolution Options:

1. Prompt Customer Re-Authorization
   • Have the customer perform a new Zero Authorization
   • Or complete a new card payment with CVV
   • Use this new payment ID for future MIT charges

Proactive Approach

Track when original authorizations are approaching expiration and prompt customers to re-authorize before it expires.

410 Gone - Payment Over Maximum Total

Error Message:

Amount exceeds limit: the total for a card-on-file transaction cannot exceed $X.XX (the allowed
multiplier of Y) of the original payment amount ($Z.ZZ).

Cause: The MIT payment amount exceeds the calculated maximum based on the customer’s payment history.

Example:

• Maximum historical payment: $10.00
• Multiplier setting: 3
• Maximum allowed MIT: $30.00
• Your request: $35.00 ❌

What This Means:

• MIT charges are limited to prevent unexpectedly large charges
• The limit is based on the customer’s maximum payment in the lookback period
• If using Zero Authorization only, the limit is based on maxZeroAuthAmount × maxMultiple

Resolution

1. Request Customer Authorization
   • For amounts significantly higher than historical payments
   • Have the customer complete a transaction with active participation where they enter their CVV

Error Handling Quick Reference

async function processMerchantInitiatedTransaction(originalPaymentId, amount) {
  try {
    const response = await fetch(
      '/api/checkout/merchant-initiated-transaction',
      {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          Authorization: 'your-merchant-api-key',
          'x-user-id': 'customer-123',
        },
        body: JSON.stringify({
          subtotal: amount,
          originalPaymentId: originalPaymentId,
        }),
      }
    );

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 403:
          // MIT not enabled
          console.error('MIT not enabled for this merchant');
          break;
        case 410:
          // Authorization expired or amount exceeded
          return handleExpiredOrExceeded(error);
        case 429:
          // Rate limit exceeded
          return handleRateLimitExceeded(error);
        default:
          throw new Error(error.message);
      }
    }

    return await response.json();
  } catch (error) {
    console.error('MIT payment failed:', error);
    throw error;
  }
}

function handleExpiredOrExceeded(error) {
  // Prompt customer for new authorization
  console.log(
    'Original authorization no longer valid, customer re-auth required'
  );
  // Redirect to re-authorization flow
}

Best Practice

For MIT implementations, maintain a system to track authorization expiration dates and proactively refresh them before they expire. This ensures uninterrupted billing for usage-based services.

Best Practices

Clearly Communicate MIT Terms

Provide clear, accessible terms explaining when and how the customer’s card will be charged. Include specifics about trigger conditions (usage thresholds, billing cycles, etc.) and estimated charge amounts.

Send Notifications Before Charges

For better customer experience and reduced disputes, send email or push notifications before processing MIT charges, especially for larger amounts or first-time charges.

Implement Idempotency

Use idempotent request patterns to prevent duplicate charges in case of network issues or retries. Track MIT attempts with unique reference IDs.

Monitor and Alert

Set up monitoring for MIT failures and velocity limit hits. Proactively reach out to customers whose authorizations are expiring or hitting limits.

Provide Clear Receipts

After each MIT charge, send a detailed receipt explaining what was charged and why. Include a way for customers to review their usage or billing history.

Frequently Asked Questions

What’s the difference between a MIT and a Card on File Transaction?

Card on File transactions require the customer to actively participate and authorize each payment at the point of sale. MITs are initiated by the merchant without customer involvement, based on prior authorization.

Can I use MIT for subscription billing?

MIT is designed for unscheduled, variable charges. For fixed recurring payments, use our Subscription feature which is optimized for regular billing cycles with predictable amounts.

What happens if the customer’s card expires?

If the stored card expires, MIT charges will fail. You’ll need to prompt the customer to update their payment method and complete a new authorization.

Are there additional fees for MIT?

No, MIT transactions are processed with the same fee structure as regular card transactions. There are no additional charges for using MIT functionality.

How do I increase the MIT limit for a customer?

The MIT limit is based on the customer’s maximum historical payment multiplied by the configured multiplier. To increase the limit, have the customer complete a regular card payment (with CVV) at a higher amount.

Next Steps

Zero Authorization

Validate and store cards without charging the customer

Card on File Transactions

Learn about customer-initiated stored credential transactions

Testing Guide

Test your MIT implementation

Webhooks

Set up webhooks for payment notifications