Integration Types
Other Features
Card Payments
Mobile Wallets
Alternative Payment Methods
Resources
The following sections describe how to submit cardholder-initiated and merchant-initiated transactions (CIT and MIT) to the Mastercard Gateway in order to comply with card scheme standards for processing these transactions:
For general information about the above scenarios, see Cardholder and Merchant-initiated Payments . For full examples of the requests for all scenarios, download the Postman collection.
Whenever you submit multiple payments in a series, the first transaction must be a CIT which provides the cardholder’s approval for the entire series. The subsequent transactions are usually MITs. In all requests, you can use the transaction.source
field to identify whether a transaction is cardholder or merchant initiated, and the sourceOfFunds.provided.card.storedOnFile
field to indicate whether the payment details are to be stored, have been previously stored, or you intend to store them. For more information, see FAQs.
A CIT transaction can be a one-off payment where you typically do not store the payment details provided by the payer. However, the payer can consent for you to store their payment details for future use (usually as part of a customer registration or account creation process) so that you can offer subsequent cardholder-initiated transactions using the stored payment details.
sourceOfFunds.type = CARD
or SCHEME_TOKEN
Value depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source = INTERNET
Value indicates to the gateway that the transaction is cardholder initiated. You can set the value to INTERNET
, MOTO
, MAIL_ORDER
, TELEPHONE_ORDER
, VOICE_RESPONSE
, or CALL_CENTER
.
INTERNET
value is used. However, you should indicate the channel through which you received the payment.sourceOfFunds.provided.card.storedOnFile = TO_BE_STORED
Value indicates that the payer agrees for you to store their payment details for future use.
In any subsequent payments initiated by the payer (not by you) and where the payer's stored payment details are used, you must provide the following fields in the request:
sourceOfFunds.type = CARD
or SCHEME_TOKEN
Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source = INTERNET
sourceOfFunds.provided.card.storedOnFile = STORED
For more details on how to indicate to the gateway how and whether the payment details are to be stored, see FAQs.
The CITs can be authenticated with 3DS to identify the cardholder and prevent fraud. You can use 3DS in:
The following table describes some detailed use cases related to 3DS authentication. For more information on both 3DS authentication in the gateway and using external authorization in payment transactions, see 3DS Authentication.
Use Case | Integration Steps |
---|---|
Agreement with the payer for recurring payments, including an initial charge in the CIT |
Step 1: Perform Authentication as described in the Authentication guidelines and specify the amount required for the initial payment. Step 2: Create the CIT request with the details defined in the Cardholder-initiated Payments section, and add one of the following:
|
Agreement with the payer for recurring payments, including no initial charge in the CIT |
This use case covers recurring payment series where no payment is due at the moment the payer signs up for the service. While performing authentication as described in the 3DS Authentication topic, use the additional fields specified in the following steps to integrate 3DS for recurring payments. Step 1: Perform the INITIATE AUTHENTICATION operation and set authentication.purpose to ADD_CARD or MAINTAIN_CARD. Step 2: Perform the AUTHENTICATE PAYER operation with the following fields:
Step 3: As the CIT request, perform the VERIFY operation request and add one of the following:
If you are using the Hosted Session integration , complete steps 1 and 2 within the session and then use the session ID (from the session created for steps 1 and 2) when sending the request from your server in step 3.
|
Add Card without Payment Agreement |
This use case covers a scenario where the payer wants to add their card details while creating their profile or customer account with you without any immediate payment. The payer can use the stored card in the future for one-off payments or to establish a payment agreement for a series of payments. Step 1: Perform the INITIATE AUTHENTICATION operation and set authentication.purpose to ADD_CARD or MAINTAIN_CARD. Step 2: Perform the AUTHENTICATE PAYER operation and set amount to 0. Step 3: As the CIT request, perform the VERIFY operation request and add one of the following:
If you are using the Hosted Session integration, complete steps 1 and 2 within the session and then use the session ID (from the session created for steps 1 and 2 when sending the request from your server in step 3.
|
The following fields are needed in the AUTHENTICATE PAYER operation to have a successful recurring transaction:
When using the API v57 - v60:
To create a CIT with the Hosted Checkout when no stored credentials exist:
interaction.saveCardForCredentialOnFile = PAYER_INITIATED_PAYMENTS
.
The Hosted Checkout provides the payer with the available payment options in the Payment options window.
interaction.operation=AUTHORIZE
) transaction request with sourceOfFunds.provided.card.storedOnFile=TO_BE_STORED
and transaction.payerConsentForStoringCardDetails=PAYER_INITIATED_PAYMENTS
.RETRIEVE_ORDER
operation request.
transaction.payerConsentForStoringCardDetails=PAYER_INITIATED_PAYMENTS
field. interaction.tokens
containing the gateway tokeninteraction.saveCardForCredentialOnFile=PAYER_INITIATED_PAYMENTS
This field allows the payer to enter new card details and store them, if they do not want to use the previous ones.
The Hosted Checkout displays the available payment options and stored cards to the payer.
To collect consent from the payer with the Hosted Checkout to store their payment details for subsequent MITs (for example, by creating a payer account in your system and storing the details against the account):
agreement.id
Unique value generated by you to identify a payment agreement with the payer. You need to submit it on subsequent MITs to link the payments in a series. This is required to comply with card scheme mandates where the agreement ID acts as an identifier to link the preceding CIT to the subsequent MITs.
agreement.type
Kind of commercial agreement that has been established with the payer.
The Hosted Checkout provides the payer with the Debit or Credit card payment options.
If the payer proceeds with giving consent, the Hosted Checkout submits the transaction request with the following values:
sourceOfFunds.provided.card.storedOnFile = TO_BE_STORED
transaction.payerConsentForStoringCardDetails = MERCHANT_INITIATED_PAYMENTS
transaction.payerConsentForStoringCardDetails = MERCHANT_INITIATED_PAYMENTS
field.You can submit recurring payments for processing to the gateway if the payer agrees for you to store their payment details for future use and you have a payment agreement with the payer that authorizes you to initiate subsequent recurring payments without the payer’s active participation.
In the initial CIT request, you need to provide the following fields to set up the agreement:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
Value depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET, and
Value indicates to the gateway that the transaction is cardholder initiated.
sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
Value indicates that the payer agrees for you to store their payment details for future use.
agreement.id
Unique value generated by you to identify a payment agreement with the payer.
agreement.type
=RECURRING
Standing instruction agreement that you have established with the payer.
agreement.numberOfPayments
agreement.amountVariability
agreement.expiryDate
agreement.paymentFrequency
agreement.minimumDaysBetweenPayments
agreement.expiryDate
agreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=MERCHANT
Value indicates to the gateway that the transaction is merchant initiated.
sourceOfFunds.provided.card.storedOnFile
=STORED
agreement.id
Value must be the same agreement.id as that provided in the initial CIT transaction. This allows the gateway to link the payments in a series and is required to comply with card scheme mandates where the agreement ID acts as an identifier to link the preceding CIT to the subsequent MITs.
You can submit installment payments for processing to the gateway if the payer agrees for you to store their payment details for future use and you have a payment agreement with the payer to split a single purchase into a number of payments processed at agreed intervals.
In the initial CIT request, you need to provide the following fields to set up the agreement:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
Value depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET
Value indicates to the gateway that the transaction is cardholder initiated.
sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
Value indicates that the payer agrees for you to store their payment details for future use.
agreement.id
Unique value generated by you to identify a payment agreement with the payer.
agreement.type
=INSTALLMENT
Standing instruction agreement that you have established with the payer.
agreement.numberOfPayments
agreement.amountVariability
agreement.expiryDate
agreement.paymentFrequency
agreement.minimumDaysBetweenPayments
agreement.expiryDate
agreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
Value indicates to the gateway that the transaction is merchant initiated.
transaction.source
=MERCHANT
sourceOfFunds.provided.card.storedOnFile
=STORED
agreement.id
Value must be the same agreement.id
as that provided in the initial CIT transaction. This allows the gateway to link the payments in a series and is required to comply with card scheme mandates where the agreement ID acts as an identifier to link the preceding CIT to the subsequent MITs.
You can submit unscheduled payments for processing to the gateway if the payer agrees for you to store their payment details for future use and you have a payment agreement with the payer that authorizes you to initiate subsequent unscheduled payments without the payer’s active participation.
In the initial CIT request, you need to provide the following fields to set up the agreement:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
Value depends on whether you are providing the raw card details or a token (having already tokenized the card details).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET
Value indicates to the gateway that the transaction is cardholder initiated.
sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
Value indicates that the payer agrees for you to store their payment details for future use.
agreement.id
Unique value generated by you to identify a payment agreement with the payer.
agreement.type
=UNSCHEDULED
Standing instruction agreement that you have established with the payer.
agreement.numberOfPayments
agreement.amountVariability
agreement.paymentFrequency
agreement.expiryDate
agreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
Value depends on whether the details have been stored by you or by the gateway (in which case you are providing a token).
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=MERCHANT
Value indicates to the gateway that the transaction is merchant initiated.
sourceOfFunds.provided.card.storedOnFile
=STORED
agreement.id
: The same agreement.id as that provided in the initial transaction. This allows the gateway to link payments in a series. Value must be the same agreement.id as that provided in the initial CIT transaction. This allows the gateway to link the payments in a series and is required to comply with card scheme mandates where the agreement ID acts as an identifier to link the preceding CIT to the subsequent MITs.
You can submit industry practice payments for processing to the gateway if the payer allows you to store their payment details for future use and authorizes you to initiate subsequent MITs without the payer's active participation.
In the industry practice MIT request, you need to provide the following fields:
order.industryPracticePaymentReason
Type of industry payment you are creating, for example, DELAYED_CHARGE, NO_SHOW_PENALTY, or PARTIAL_SHIPMENT.
sourceofFunds.provided.card.storedOnFiles = STORED
Value indicates that the payer has agreed for you to store their payment details for future use.
referenceOrderId
Order ID from the previous CIT. Gateway uses this field to look up Trace ID for the previous CIT.
transaction.acquirer.traceid
Trace ID. This field contains the authorizationResponse.transactionIdentifier from the response of the initial CIT in the series. This field is needed only if the reference order ID is not availableShould you provide Agreement ID and not provide Reference Order ID or Trace ID on Mastercard transacted cards, Gateway will provide a default gateway Trace ID.
Initial CIT:
order.id
= "OD12345"transaction.id
= "TRAN 1"agreement.id =
= "AGR 1"sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
= INTERNET
sourceOfFunds.provided.card.storedOnFile
= TO_BE_STORED
Subsequent industry practice MIT, submitted as a new order, due to a delayed charge:
order.id
= "OD45678"
transaction.id
= "TRAN 2"agreement.id =
= "AGR 1"sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
= MERCHANT
sourceOfFunds.provided.card.storedOnFile
= STORED
order.industryPracticePaymentReason
= DELAYED_CHARGE
referenceOrderId
= "OD12345"
You can resubmit failed payments for processing to the gateway if the payer has agreed for you to store their payment details for future use and the issuer’s response to the failed payment does not prohibit you from trying again later.
In the MIT resubmission request, you need to provide the following fields:
order.id
In case of an MIT resubmission, use the same order ID as in the first MIT, but a new transaction.id, as the gateway does not allow duplicate transaction IDs within the same order.
transaction.resubmission = "true"
Indication that this MIT is a resubmission for a previous failed authorization.
referenceOrderId
Order ID from the previous CIT. Gateway uses this field to look up Trace ID for the previous CIT.
transaction.acquirer.traceid
Trace ID. This field contains the authorizationResponse.transactionIdentifier
from the response of the initial CIT in the series. This field is needed only if the reference order ID is not.
Initial CIT:
order.id
= "OD12345"transaction.id
= "TRAN 1"agreement.id
= "AGR 1"sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
= INTERNET
sourceOfFunds.provided.card.storedOnFile
= TO_BE_STORED
First MIT, submitted as a new order, as an industry practice payment due to delayed charge:
order.id
= "OD5678"
transaction.id
= "TRAN 2"sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
= MERCHANT
sourceOfFunds.provided.card.storedOnFile
= STORED
order.industryPracticePaymentReason
= DELAYED_CHARGE
referenceOrderId
= "OD12345"
After the first MIT fails due to insufficient funds, a second MIT is sent as a resubmission (same order):
order.id
= "OD5678"
transaction.id
= "TRAN 3"sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
= MERCHANT
sourceOfFunds.provided.card.storedOnFile
= STORED
order.industryPracticePaymentReason
= DELAYED_CHARGE
transaction.resubmission
="true"
To comply with the card scheme standards for processing CITs and MITs, you must use the sourceOfFunds.provided.card.storedOnFile
field to indicate to the gateway if the payment details are stored, not stored, or you intend to store them.
For the initial CIT:
sourceOfFunds.provided.card.storedOnFile
field in the request. sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
. This indicates to the gateway that the payer has agreed for you to store their payment details. You must set this value irrespective of:
If you are using Hosted Checkout or Hosted Session, you can store the payment details using gateway or network tokenization after the initial CIT has been done and the payer has provided their payment details to the gateway. Use the CREATE OR UPDATE TOKEN operation with the relevant session ID.
If you are using Direct Payment or Hosted Batch, you can store the details before or after the initial CIT is complete.
sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
. This indicates to the gateway that you will be using these details for future MIT transactions.For subsequent payments, set sourceOfFunds.provided.card.storedOnFile
=STORED
to indicate that credential on file is used in the payment. This also applies in situations when the payer returns and their stored payment details are used for a new CIT which requires no new agreement for future MITs.
If you do not have a unique identifier for your agreement with the payer, you can:
Always use an agreement ID if possible, as it is a unique value indication between you and the payer. For example, if the payer needs to renew their insurance policy, the agreement ID can be the policy number.
In some situations, you may not have access to the original agreement ID. For example:
In these cases, you cannot generate a new agreement ID, but need to use a reference order ID or trace ID instead.
The reference Order ID reflects the latest order within the transaction series. For example, if the transaction series consists of an initial CIT and 2 subsequent MITs:
The trace ID (also called scheme transaction ID) is a unique identifier all schemes issue for each transaction processed through them. The trace ID is used to identify associated transactions, for example:
The schemes use different methods to generate this ID:
No. If you do not intend to charge the payer when establishing a payment agreement with them, for example, in case of a magazine subscription where the first payment is scheduled in 30 days, you must submit a VERIFY request with the agreement details:
agreement.id
agreement.type
The Verify transaction becomes the first CIT in the series. For any subsequent payments, use the agreement.id
to link payments in the series.
If the payer has been authenticated in the gateway using 3DS authentication, you can provide the authentication.transactionId
from the gateway authentication result in the VERIFY request to link the authentication to the payment agreement. For externally authenticated transactions, see the FAQs in 3DS Authentication.
The payment details against an agreement can change if, for example:
If card details have changed (except in case of reissue of expired card and network tokens), you must perform a CIT using the original agreement ID to update the payment details or gateway token before performing any MITs with the new card number. Depending on your business model, you can also decide to create a new agreement with the payer.
If you are using network tokenization, the schemes can automatically update the card number stored against the network token in the gateway.