Credential on File Transactions
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:
- Cardholder-initiated payments:
- Merchant-initiated payments:
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.
- The above scenarios are supported from API v74 onwards.
- To be able to submit any MITs, your Your payment service provider (PSP) must have MERCHANT enabled as an allowable transaction source on your merchant acquirer link.
- If you want to store the payer’s payment details in the gateway and use a token to refer to the stored details, your PSP must configure merchant profile for gateway tokenization.
CITs in general
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.
- In the initial transaction request with a new customer, you need to provide the following fields:
sourceOfFunds.type = CARD
orSCHEME_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 orsourceOfFunds.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
, orCALL_CENTER
.sourceOfFunds.provided.card.storedOnFile = TO_BE_STORED
Value indicates that the payer agrees for you to store their payment details for future use.
INTERNET
value is used. However, you should indicate the channel through which you received the payment.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
orSCHEME_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 orsourceOfFunds.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.
CITs with 3DS
The CITs can be authenticated with 3DS to identify the cardholder and prevent fraud. You can use 3DS in:
- One-off CITs
- CITs which form the first step in a series of payments, where the subsequent ones are MITs
- Scenarios where you want to authenticate the cardholder when adding their card to the customer account for future use
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 v61 or later:
- agreement.id
- agreement.type=RECURRING
- agreement.numberOfPayments
- agreement.amountVariability
- agreement.expiryDate
- agreement.paymentFrequency
- agreement.minimumDaysBetweenPayments
When using the API v57 - v60:
- agreement.id
- agreement.type=RECURRING
- agreement.expiryDate
- agreement.recurring.daysBetweenPayments
CITs with the Hosted Checkout and stored credentials
To create a CIT with the Hosted Checkout when no stored credentials exist:
- Send an INITIATE CHECKOUT operation request with
interaction.saveCardForCredentialOnFile = PAYER_INITIATED_PAYMENTS
.The Hosted Checkout provides the payer with the available payment options in the Payment options window.
- Credential on file with Hosted Checkout scenarios are supported from API v74 and onwards.
- If you support the Click to Pay payment method, the Hosted Checkout does not display it separately on its payment page. The payer is asked for their email address, and if the payer has a Click to Pay profile, the cards they have stored for their profile are listed in the Debit or credit section.
- The payer selects Debit or Credit.
The Hosted Checkout does not display or link to the Terms and Conditions or Privacy Policies. It is your responsibility to provide these details to the payer as required by any regulatory regulations or privacy laws
- The payer can pay with or without providing consent to the gateway, that is, with or without selecting the Save this card for future purchases checkbox.
- If the payer proceeds to pay without giving consent, the payment process works as usual.
- If the payer proceeds to pay with giving consent, then the Hosted Checkout:
- Sets the correct Card on File indicator
- Submit the PAY (if
interaction.operation=AUTHORIZE
) transaction request withsourceOfFunds.provided.card.storedOnFile=TO_BE_STORED
andtransaction.payerConsentForStoringCardDetails=PAYER_INITIATED_PAYMENTS
.
You must comply with scheme and regulatory requirements (For example, GDPR). You must provide the payer with an option to remove the consent and delete the gateway token.
If the payer pays with a method other than a credit card, such as ACH (Automated Clearing House) or PayPal, the standard checkout procedure applies. The gateway only stores card details, so if you want to store any payment details related to other payment methods, you must do it yourself after receiving payer consent. - After the gateway returns the payer to your store's website, submit a
RETRIEVE_ORDER
operation request.- If the payer has provided consent, the response contains the
transaction.payerConsentForStoringCardDetails=PAYER_INITIATED_PAYMENTS
field. - To create the token that you can use to refer to the credentials stored in the gateway, use the CREATE OR UPDATE TOKEN operation. For more details, see Gateway Tokenization.
- If the payer has provided consent, the response contains the
- For any subsequent cardholder-initiated payment, send the INITIATE CHECKOUT operation request with:
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.
- If the payer selects Debit or credit, the details for the token are listed and the payer can choose to pay with the token or add the details for another card.
CITs with the Hosted Checkout for authorizing MITs
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):
- Send an INITIATE CHECKOUT operation request with:
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.
- Credential on file with Hosted Checkout scenarios are supported from API v74 and onwards.
- The agreement details are only needed if you intend to process MITs related to the CIT later. If you only intend to process CITs with the stored payment details, no agreement is needed.
The Hosted Checkout provides the payer with the Debit or Credit card payment options.
- You must comply with scheme and regulatory requirements, for example, GDPR. You must provide the payer with an option to remove the consent and delete the stored credentials.
- It is your responsibility to ensure that items that do not need agreements are not included in the order or transaction.
- The payer can proceed forward only by giving consent, that is, by selecting the checkbox. The pay button is disabled until they select the checkbox.
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
- After the gateway returns the payer to your web site, submit a RETRIEVE ORDER operation request:
- If the payer has provided consent, the response contains the
transaction.payerConsentForStoringCardDetails = MERCHANT_INITIATED_PAYMENTS
field. - If the payer has not provided consent, the payer cannot proceed (cart is abandoned).
- If the payer has provided consent, the response contains the
Merchant-initiated recurring payments
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
orSCHEME_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 orsourceOfFunds.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.
- When using the API v61 and onwards:
agreement.numberOfPayments
agreement.amountVariability
agreement.expiryDate
agreement.paymentFrequency
agreement.minimumDaysBetweenPayments
- When using the API v57 - v60:
agreement.expiryDate
agreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type
=CARD
orSCHEME_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 orsourceOfFunds.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.
Merchant-initiated installment payments
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
orSCHEME_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 orsourceOfFunds.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.
- When using the API v61 and onwards:
agreement.numberOfPayments
agreement.amountVariability
agreement.expiryDate
agreement.paymentFrequency
agreement.minimumDaysBetweenPayments
- When using the API v57 - v60:
agreement.expiryDate
agreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type
=CARD
orSCHEME_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 orsourceOfFunds.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.
Merchant-initiated unscheduled payments
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
orSCHEME_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 orsourceOfFunds.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.
- When using the API v61 and onwards:
agreement.numberOfPayments
agreement.amountVariability
agreement.paymentFrequency
- When using the API v57 - v60:
agreement.expiryDate
agreement.recurring.daysBetweenPayments
In any subsequent MIT requests, you must provide the following fields:
sourceOfFunds.type
=CARD
orSCHEME_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 orsourceOfFunds.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.
Merchant-initiated industry practice payments
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 available. If 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.
Industry practice flow example
Initial CIT:
order.id
= "OD12345"transaction.id
= "TRAN 1"agreement.id =
= "AGR 1"sourceOfFunds.type
=CARD
orSCHEME_TOKEN
sourceOfFunds.provided.card.*
fields orsourceOfFunds.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
orSCHEME_TOKEN
sourceOfFunds.provided.card.*
fields orsourceOfFunds.token
transaction.source
=MERCHANT
sourceOfFunds.provided.card.storedOnFile
=STORED
order.industryPracticePaymentReason
=DELAYED_CHARGE
referenceOrderId
="OD12345"
Merchant-initiated resubmission payments
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.
- If previous CIT was performed outside the gateway, you should instead provide:
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. - If 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.
Resubmission flow example
Initial CIT:
order.id
= "OD12345"transaction.id
= "TRAN 1"agreement.id
= "AGR 1"sourceOfFunds.type
=CARD
orSCHEME_TOKEN
sourceOfFunds.provided.card.*
fields orsourceOfFunds.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
orSCHEME_TOKEN
sourceOfFunds.provided.card.*
fields orsourceOfFunds.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
orSCHEME_TOKEN
sourceOfFunds.provided.card.*
fields orsourceOfFunds.token
transaction.source
=MERCHANT
sourceOfFunds.provided.card.storedOnFile
=STORED
order.industryPracticePaymentReason
=DELAYED_CHARGE
transaction.resubmission
="true"
FAQs
How do I indicate to the gateway how the payment details are handled?
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:
- If it is a one-off payment and you do not intend to store payment details, omit the
sourceOfFunds.provided.card.storedOnFile
field in the request. -
If this is the first time the payer is doing business with you, and their payment details have not been stored previously, but you now intend to store them for future use, set
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:- How you store the payment details — in your own app or web site (requires you to be PCI-compliant), or using gateway or network tokenization.
- Whether you store the payment details before or after submitting the transaction to the gateway.
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.
- If the payer is a returning customer and you have stored their payment details earlier for a different order, you have no need to store their payment details again. However, if you use the new CIT to create an agreement with the payer for future MITs related to this CIT, set
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.
What if I do not have an agreement ID?
If you do not have a unique identifier for your agreement with the payer, you can:
- Generate an agreement ID for the purpose of the interaction with the gateway. You must then store it and submit it to the gateway on all payments in the series, including the CIT.
- Use an existing identifier (that you are already storing in your system), for example, the order ID for the first payment in the series.
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:
- Agreement was made a long time ago and the details were not kept on record.
- You are unaware of the initial agreement ID or it was made in another payment gateway.
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:
- Initial CIT has the order ID = 1
- First MIT has the order ID = 2 and uses the reference Order ID = 1 (as it refers to the initial CIT)
- Second MIT has the order ID = 3 and uses the reference Order ID = 2 (as it refers to the first MIT, which is the latest order ID in the series)
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:
- Subsequent CAPTURE transaction
- Reversal of a transaction
- Linked REFUND AUTHORIZATION transaction
- Subsequent transaction in a series of recurring, installment, or unscheduled payments
- AUTHORIZATION to be updated
The schemes use different methods to generate this ID:
- Mastercard generates an ID that combines:
- 3-digit financial network code
- Banknet Reference Number (AN6)
- Transaction date (MMDD)
- VISA generates an ID that is unique for each original transaction.
- Amex generates an ID that is unique for each original transaction.
Do I need to submit a payment when establishing the payment agreement?
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.
What if the payment details for an agreement change?
The payment details against an agreement can change if, for example:
- Payer lost their card and was issued a new card.
- Payer changed their bank.
- Card had insufficient funds and the payer provided other payment details
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.