> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.coinflow.cash/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coinflow.cash/_mcp/server. # 🏪 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 > **Warning** > > **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: | Feature | Card on File | Subscriptions | Merchant Initiated (MIT) | | -------------------- | ---------------- | ----------------- | ------------------------ | | **Initiator** | Customer | Automatic | Merchant | | **Schedule** | On-demand | Fixed recurring | Variable | | **Customer Present** | Yes | Initially | No | | **Use Case** | Repeat purchases | Recurring billing | Usage charges, top-ups | | **Consent Required** | Per transaction | Once, at signup | Once, with conditions | > 💡 **Need Fixed Recurring Payments?** > > If you need automated payments on a fixed schedule (monthly, weekly, etc.), check out our [Subscriptions Overview](/guides/subscriptions/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. ```bash POST /api/checkout/zero-authorization/{merchantId} ``` **Request Body:** ```json { "card": { "number": "4111111111111111", "expiryMonth": "12", "expiryYear": "2025", "cvv": "123" } } ``` Or use a previously tokenized card: ```json { "token": "4111114324324111_bt" } ``` > **Info** > > **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:** ```bash POST /api/checkout/card/{merchantId} ``` ```json { "subtotal": { "cents": 1500, "currency": "USD" }, "token": "4111114324324111_bt" } ``` **Using a New Card:** ```json { "subtotal": { "cents": 1500, "currency": "USD" }, "card": { "number": "4111111111111111", "expiryMonth": "12", "expiryYear": "2025", "cvv": "123" } } ``` **Response:** ```json { "paymentId": "550e8400-e29b-41d4-a716-446655440000" } ``` > **Info** > > **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. ```bash POST /api/checkout/merchant-initiated-transaction ``` [View MIT API Reference](/api-reference/api-reference/checkout/merchant-initiated-transaction) **Request Parameters:** | Parameter | Required | Description | | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- | | `subtotal` | Yes | The amount to charge. Object with `cents` (integer) and `currency` (e.g., "USD") | | `originalPaymentId` | Yes | The payment ID from the Zero Authorization or initial CVV-verified transaction | | `settlementType` | No | Specify the payment settlement type (e.g., "Bank", "Credits", "USDC") | | `webhookInfo` | No | Custom webhook data to be sent to your webhook endpoint if configured | | `presentment` | No | The currency to charge the customer's card (e.g., "EUR"). If different from subtotal currency, conversion will be applied | | `statementDescriptor` | No | If the bank supports dynamic descriptors, this text will appear on the customer's statement | | `authOnly` | No | Only authorize the purchase without capturing. Default: `false` | | `feePercentage` | No | Marketplace fee percentage taken from subtotal (0-100). Used for seller/submerchant transactions | | `fixedFee` | No | Fixed amount marketplace fee taken from subtotal. Object with `cents` value | | `destinationAuthKey` | No | JWT token for USDC settlement to addresses other than your main merchant settlement address | | `accountFundingTransaction` | No | Account funding transaction details if applicable | #### 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:** ```json { "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: ```json { "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: **`Zero Authorization`** ```bash Zero Authorization 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" }' ``` **`Zero Auth Response`** ```json Zero Auth Response { "paymentId": "550e8400-e29b-41d4-a716-446655440000" } ``` **`MIT Request`** ```bash MIT Request 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" }' ``` **`MIT Response`** ```json MIT Response { "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: **`Initial Purchase (Saved Token)`** ```bash Initial Purchase (Saved Token) 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" }' ``` **`Initial Purchase (New Card)`** ```bash Initial Purchase (New Card) 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" } }' ``` **`Initial Purchase Response`** ```json Initial Purchase Response { "paymentId": "550e8400-e29b-41d4-a716-446655440000" } ``` **`MIT Request`** ```bash MIT Request 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" }' ``` **`MIT Response`** ```json MIT Response { "paymentId": "650e8400-e29b-41d4-a716-446655440001" } ``` > **Warning** > > **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. > **Info** > > **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 ```json "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 > **Tip** > > **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 ```javascript 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 } ``` > **Success** > > **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](/guides/checkout/payment-scenarios/subsequent-transactions/zero-authorization) Validate and store cards without charging the customer #### [Card on File Transactions](/guides/checkout/payment-scenarios/subsequent-transactions/card-on-file) Learn about customer-initiated stored credential transactions #### [Testing Guide](/guides/checkout/testing/testing-credit-cards) Test your MIT implementation #### [Webhooks](/guides/developer-resources/webhooks/checkout-webhooks) Set up webhooks for payment notifications