🏪 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

Use Cases for MIT

How It Works

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

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

1
{
2
  "card": {
3
    "number": "4111111111111111",
4
    "expiryMonth": "12",
5
    "expiryYear": "2025",
6
    "cvv": "123"
7
  }
8
}

1
{
2
  "token": "4111114324324111_bt"
3
}

$
POST /api/checkout/card/{merchantId}

1
{
2
  "subtotal": {
3
    "cents": 1500,
4
    "currency": "USD"
5
  },
6
  "token": "4111114324324111_bt"
7
}

1
{
2
  "subtotal": {
3
    "cents": 1500,
4
    "currency": "USD"
5
  },
6
  "card": {
7
    "number": "4111111111111111",
8
    "expiryMonth": "12",
9
    "expiryYear": "2025",
10
    "cvv": "123"
11
  }
12
}

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

$
POST /api/checkout/merchant-initiated-transaction

1
{
2
  "subtotal": {
3
    "cents": 2500,
4
    "currency": "USD"
5
  },
6
  "originalPaymentId": "550e8400-e29b-41d4-a716-446655440000",
7
  "settlementType": "USDC"
8
}

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

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"
>
  }'

$
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": "USDC"
>
  }'

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/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": "USDC"
>
  }'

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.

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

1
"enabled": true,
2
"maxCount": 5,
3
"period": 86400,
4
"maxMultiple": 3,
5
"expiration": 2592000,
6
"maxZeroAuthAmount": { "cents": 2000 },
7
"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

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

Cannot perform card on file operations for mobile wallet payments

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

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

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

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).

Error Handling Quick Reference

1
async function processMerchantInitiatedTransaction(originalPaymentId, amount) {
2
  try {
3
    const response = await fetch(
4
      '/api/checkout/merchant-initiated-transaction',
5
      {
6
        method: 'POST',
7
        headers: {
8
          'Content-Type': 'application/json',
9
          Authorization: 'your-merchant-api-key',
10
          'x-user-id': 'customer-123',
11
        },
12
        body: JSON.stringify({
13
          subtotal: amount,
14
          originalPaymentId: originalPaymentId,
15
        }),
16
      }
17
    );
18
19
    if (!response.ok) {
20
      const error = await response.json();
21
22
      switch (response.status) {
23
        case 403:
24
          // MIT not enabled
25
          console.error('MIT not enabled for this merchant');
26
          break;
27
        case 410:
28
          // Authorization expired or amount exceeded
29
          return handleExpiredOrExceeded(error);
30
        case 429:
31
          // Rate limit exceeded
32
          return handleRateLimitExceeded(error);
33
        default:
34
          throw new Error(error.message);
35
      }
36
    }
37
38
    return await response.json();
39
  } catch (error) {
40
    console.error('MIT payment failed:', error);
41
    throw error;
42
  }
43
}
44
45
function handleExpiredOrExceeded(error) {
46
  // Prompt customer for new authorization
47
  console.log(
48
    'Original authorization no longer valid, customer re-auth required'
49
  );
50
  // Redirect to re-authorization flow
51
}

Best Practices

Frequently Asked Questions

Next Steps