Online Payments

Cardholder vs merchant-initiated transactions

Cardholder-initiated transactions (CIT) and merchant-initiated transactions (MIT) use stored credentials, known as Card-on-File (COF), to process repeat/recurring payments securely without the consumer re-entering the card data.

By providing the following details, you can reduce issuer declines, increase approval rates, and provide a smoother experience for the consumer:

CIT/MIT details
Detail to provide	Description	Field name
Who initiated the transaction	Specify if the transaction is a CIT or MIT. Valid values are: `CARDHOLDER` - Cardholder-initiated transaction `MERCHANT` - Merchant-initiated transaction	`initiatorType`
The storage status of the card	Specify if the card is stored, needs to be stored, or entered by the cardholder. Valid values are: `STORED` - Already stored with the merchant `TO_BE_STORED` - Needs to be stored `NOT_STORED` - if the cardholder entered it themselves.	`accountOnFile`
Reference of the original transaction	Specify the original transaction ID for merchant-initiated transactions. This provides a link back to the original transaction where the cardholder gave consent.	`originalNetworkTransactionId`

How CIT and MIT work

The CIT and MIT lifecycle consists of the following steps:

Cardholder initiates the transaction (CIT) via POST /payments and chooses to store their card or start a recurring relationship.
The Payments API returns the networkResponse.networkTransactionId in the response.
You store the original transaction ID (networkResponse.networkTransactionId) from the response.
You initiate an MIT transaction for subsequent charges by sending the stored value (networkTransactionId from the CIT response) in the field card.originalNetworkTransactionId to link back to the original cardholder consent.

Note

If you receive an account update for a card through Account Updater, Real-Time Account Updater, or from the cardholder themselves, you don't need to create a new CIT transaction. You can still reference the original transaction ID from the previous card account credential.

Attention

For Mastercard merchant-initiated transactions (MIT), you must send the transactionLinkId of the cardholder-initiated transaction (CIT) as the originalTransactionLinkId. For more information, refer to Mastercard transaction link identifier.

Use cases

The following table lists the use cases and field value combinations that must be sent in your requests:

Use cases and field combinations
Use case	`initiatorType`	`accountOnFile`
One-time purchase without storing card details	CARDHOLDER	NOT_STORED or not sent in the request.
Storing credentials for the first time	CARDHOLDER	TO_BE_STORED
Returning consumer making a purchase using a stored card	CARDHOLDER	STORED
Merchant-initiated transaction using a stored card	MERCHANT	STORED
Merchant-initiated transaction related to a single purchase in which the card was stored to complete one transaction. (This use case is only valid when `authorizationPurpose` field is populated)	MERCHANT	NOT_STORED, STORED, or not sent in the request.

Field details

The following table lists the key fields required for CIT and MIT transactions:

Required field details for CIT and MIT
Core fields	Description
`initiatorType`	Identifies who initiated the transaction. Valid values are: `CARDHOLDER` - Cardholder-initiated transaction. `MERCHANT` - Merchant-initiated transaction. If no value is provided, it defaults to CARDHOLDER.
`accountOnFile`	The status of the card credentials. Valid values are: `STORED` - Already stored with the merchant. `TO_BE_STORED` - Needs to be stored. `NOT_STORED` - If the cardholder entered it themselves.
paymentMethodType.card.`originalNetworkTransactionId`	The network transaction identifier from the first payment in a merchant-initiated series.
paymentMethodType.card.`accountNumberType`	The type of payment method associated with the account number. Valid values are: `PAN` - Use this value when the consumer keys in the debit or credit card account number or uses an account on file. `NETWORK_TOKEN` - Use this value when you are providing a network token. `DEVICE_TOKEN` - Use this value if you are providing a DPAN or Device PAN. `SAFETECH_TOKEN` - Use this value if you are providing a Safetech token. If no value is provided, it defaults to PAN.
Recurring & Installment fields	Description
recurring.`recurringSequence`	Identifies whether payment is the first in a series of recurring payments or a subsequent payment. Valid values are: `FIRST` `SUBSEQUENT`
recurring.`isVariableAmount`	Indicates if the recurring amount is a variable amount rather than a fixed amount. Valid values are: `true` - Variable amount `false` - Fixed amount. If no value is provided, it defaults to false. Value of true is required for Mastercard recurring transactions in which the recurring amount can vary.
recurring.`recurringNumber`	The sequence of the recurring payment numerically. Required only for Cartes Bancaires.
installment.`installmentCount`	The current installment number.
installment.`totalInstallments`	Total number of installments in the recurring plan.
Special MIT use case fields	Description
`authorizationPurpose`	This field should be populated when there is a specific authorization purpose such as delayed authorizations, reauthorizations, resubmissions, and no-shows. Valid values are: DELAYED_CHARGE NO_SHOW REAUTHORIZATION RESUBMISSION
paymentMethodType.card.authentication.`scaExemptionReason`	The justification for why a transaction does not have to meet Strong Customer Authentication (SCA) requirements. This field only applies for EU MITs.

Scenarios

The following sample code blocks show how requests must be sent for various scenarios.

Save a card for the first time (CIT)

HTTP Method: POST
Endpoint: /payments
Scenario: When a cardholder saves their card during checkout to be used in subsequent payments.

Json

{
    "captureMethod": "NOW",
    "amount": 10000,
    "currency": "USD",
    "initiatorType": "CARDHOLDER",
    "accountOnFile": "TO_BE_STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name"
        },
        "merchantCategoryCode": "4899"
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": "4012000033330026",
            "expiry": {
                "month": 10,
                "year": 2040
            }
        }
    }
}

Key response field:

networkResponse.networkTransactionId - Store this value. Required for subsequent MIT charges.

Note

If you are storing a card for the first time but don't want to charge the cardholder, use POST /verifications with the same fields (no amount). The verification response also returns a networkTransactionId you can use for the subsequent MITs.

Enroll in recurring billing (CIT)

HTTP Method: POST
Endpoint: /payments
Scenario: When a cardholder signs up for a subscription.

Json

{
    "captureMethod": "NOW",
    "amount": 10000,
    "currency": "USD",
    "initiatorType": "CARDHOLDER",
    "accountOnFile": "TO_BE_STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name"
        },
        "merchantCategoryCode": "4899"
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": "4012000033330026",
            "expiry": {
                "month": 10,
                "year": 2040
            }
        }
    },
    "recurring": {
        "recurringSequence": "FIRST"
    }
}

Note

For Mastercard: You must send the recurring.isVariableAmount.

For Cartes Bancaires:

You must send the recurring.recurringNumber.
On the initial CIT, capture the 3DS authentication values from the response. This must be replayed on every subsequent MIT in paymentMethodType.card.authentication.initialThreeDSAuthenticationResults. For more information, refer to Processing recurring and subscription transactions for Cartes Bancaires.

Charge a saved card (recurring MIT)

You must send the networkResponse.networkTransactionId value, from the initial CIT response, in the card.originalNetworkTransactionId field in your MIT request.

HTTP Method: POST
Endpoint: /payments
Scenario: A scheduled follow-up charge using a MIT.

Json

{
    "captureMethod": "NOW",
    "amount": 10000,
    "currency": "USD",
    "initiatorType": "MERCHANT",
    "accountOnFile": "STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name"
        },
        "merchantCategoryCode": "4899"
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": "4012000033330026",
            "originalNetworkTransactionId": "012125692162451",
            "expiry": {
                "month": 10,
                "year": 2040
            }
        }
    },
    "recurring": {
        "recurringSequence": "SUBSEQUENT"
    }
}

Unscheduled charge (MIT)

For unscheduled payments, the recurring object is not required.

HTTP Method: POST
Endpoint: /payments
Scenario: For one-off merchant charges against stored credentials — usage-based billing, top-ups, pay-as-you-go.

Json

{
    "captureMethod": "NOW",
    "amount": 5000,
    "currency": "USD",
    "initiatorType": "MERCHANT",
    "accountOnFile": "STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name"
        },
        "merchantCategoryCode": "4899"
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": "4012000033330026",
            "originalNetworkTransactionId": "012125692162451",
            "expiry": {
                "month": 10,
                "year": 2040
            }
        }
    }
}

Subsequent installment payment (MIT)

HTTP Method: POST
Endpoint: /payments
Scenario: A follow-up installment charge using a MIT.

Json

{
    "captureMethod": "NOW",
    "amount": 5000,
    "currency": "USD",
    "initiatorType": "MERCHANT",
    "accountOnFile": "STORED",
    "merchant": {
        "merchantSoftware": {
            "companyName": "Payment Company",
            "productName": "Application Name"
        },
        "merchantCategoryCode": "4899"
    },
    "paymentMethodType": {
        "card": {
            "accountNumber": "4012000033330026",
            "originalNetworkTransactionId": "012125692162451",
            "expiry": {
                "month": 10,
                "year": 2040
            }
        }
    },
    "installment": {
        "installmentCount": 3,
        "totalInstallments": 12
    }
}

Note

When installmentCount equals the totalInstallments, the installment chain concludes. Do not submit additional installments after this point.

MIT scenarios with authorization purpose

All of these MIT scenarios must have the following in their request:

Set initiatorType to MERCHANT
Set accountOnFile to STORED (optional for scenarios with authorizationPurpose)
Send the transaction ID from the initial CIT in card.originalNetworkTransactionId.

Additional MIT scenarios with authorizationPurpose
Scenario	`authorizationPurpose`	When to use	Example
Delayed charge	DELAYED_CHARGE	Charge after service delivery for incidentals.	Hotel minibar or fuel pump final amount.
No show	NO_SHOW	Penalty charge for missed reservation.	Hotel or restaurant no-show fee.
Resubmission	RESUBMISSION	Retry a previously declined MIT (goods already delivered).	Retry after insufficient funds.
Reauthorization	REAUTHORIZATION	New authorization when original expired before fulfillment.	Split shipment or backordered item

For NO_SHOW, RESUBMISSION, and REAUTHORIZATION, the request structure is identical - only the authorizationPurpose value changes.

HTTP Method: POST
Endpoint: /payments
Scenario: A delayed charge for the hotel minibar bill.

Json

{
    "captureMethod": "NOW",
    "amount": 2500,
    "currency": "USD",
    "initiatorType": "MERCHANT",
    "accountOnFile": "STORED",
    "authorizationPurpose": "DELAYED_CHARGE",
    "paymentMethodType": {
        "card": {
            "accountNumber": "4012000033330026",
            "originalNetworkTransactionId": "012125692162451",
            "expiry": { 
                 "month": 10, 
                 "year": 2040 
            }
        }
    }
}

SCA exemptions for MIT

If the initial CIT completed 3D Secure, subsequent MITs can claim a Strong Customer Authentication (SCA) exemption by adding card.authentication.scaExemptionReason in the request.

The following table lists the SCA exemption reason values for MIT and when they can be used:

SCA exemptions for MIT
`scaExemptionReason`	When to use
RECURRING_PAYMENT	Scheduled recurring MIT (fixed amount, fixed interval).
MERCHANT_INITIATED_TRANSACTION	Unscheduled MIT.

For more information on 3D Secure and SCA, refer to 3D Secure.

Authorize and capture a payment
Stored payments
Recurring payments
Tokenization
Real-Time Account Updater
Verify a payment method
3D Secure

Cardholder vs merchant-initiated transactions

How CIT and MIT work

Use cases

Field details

Scenarios

Save a card for the first time (CIT)

Enroll in recurring billing (CIT)

Charge a saved card (recurring MIT)

Unscheduled charge (MIT)

Subsequent installment payment (MIT)

MIT scenarios with authorization purpose

SCA exemptions for MIT

Related