This page describes how to submit cardholder initiated and merchant initiated transactions to the gateway in order to comply with card scheme standards for processing these transactions.
You may have an integration where you collect payment details from your payers, store them, and then use them to process future payments for payers. If so, provide information to the gateway in the initial transaction that you are storing payment details and intending to use them for future use. You must also provide this information to the gateway when you use the stored payment details to perform subsequent payments, either initiated by the payer (cardholder initiated transaction) or by you as the merchant, as a result of a payment agreement with the payer (merchant initiated transaction).
This is to comply with card scheme standards for processing cardholder initiated and merchant initiated payments using stored payment details (also know as Credential on File (COF) requirements). Submitting information to the gateway to identify stored payment details, cardholder initiated transactions, and merchant initiated transactions can provide
The gateway supports the following payments using stored payment details from the WS API v74 onwards:
You can use 3-D Secure with Cardholder Initiated Payments. For further information, read the following specific details.
A cardholder initiated transaction is a transaction that is performed with the active participation of the payer. For example, e-commerce, mail or telephone order transaction.
To indicate that the transaction was initiated by the payer, you must set transaction.source
to INTERNET
/MOTO
/MAIL_ORDER
/TELEPHONE_ORDER
/VOICE_RESPONSE
/CALL_CENTER
. Throughout this guide, we use an Internet payment (transaction.source
=INTERNET
) to illustrate a cardholder initiated transaction; however, you can change it to any of the other allowable values.
A cardholder initiated transaction may be a one-off payment where you will typically not store the payment details provided by the payer. However, you can enter an agreement with the payer to store their payment details for future use (usually as part of a customer registration or account creation process) and perform subsequent cardholder initiated transactions using the stored payment details.
Where, during a payer interaction, the payer agrees for you to store their payment details for future use, you need to provide the following fields in the initial transaction:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET, and
sourceOfFunds.provided.card.storedOnFile
:TO_BE_STORED.
For subsequent payments initiated by the payer (not by you) and where the payer's stored payment details are used, you must provide:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET, and
sourceOfFunds.provided.card.storedOnFile
:STORED.
For information on how to indicate to the gateway if the payment details are stored, not stored, or you intend to store them, see FAQs.
A merchant initiated transaction is a transaction that is performed using stored payment details but without the active participation of the payer. You may be performing merchant initiated transactions, if you offer:
Agreement Data use cases
In the preceding use cases, you will need to enter into an agreement with the payer about these services. The payer must agree with you to store their payment details for this purpose and allow you to subsequently initiate payments with the stored payment details without their active participation.
Industry Practice Payment use cases
Resubmission Payment use case
When you enter an agreement with the payer that allows you to subsequently submit merchant initiated payments, you must provide the following agreement details in the initial transaction in the series, that is, the cardholder initiated transaction:
agreement.id
: Specifies a unique value generated by you to identify a payment agreement with the payer. You also need to submit it on subsequent merchant initiated transactions to link 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 cardholder initiated transaction to the subsequent merchant initiated payments. agreement.type
: Indicates whether the commercial agreement with the payer has been established. You only need to provide it when you establish the agreement with the payer, that is, in the cardholder initiated transaction.
Agreement Details API Reference [REST][NVP]
When you enter an agreement with the payer that allows a merchant to subsequently submit merchant initiated industry Practice payments, the merchant needs to provide the following details:
order.industryPracticePaymentReason
- This field is used to classify merchant initiated payments that are submitted in the context of certain industry practices. Use this field to indicate the reason for that industry practice payment. For example, DELAYED_CHARGE, NO_SHOW_PENALTY, or PARTIAL_SHIPMENT.sourceofFunds.provided.card.storedOnFiles = STORED
- This field indicates consent where the merchant must have obtained the payer's consent prior to submitting industry practice transactions.transaction.resubmission
- This field indicates that this merchant initiated transaction is a resubmission for a previous authorization which failed due to insufficient funds. The operations to be resubmitted must be only Authorize or Pay.referenceOrderId
- This field indicates the reference to an order previously submitted by you to the gateway. It is applicable to the following scenarios when submitting payment transactions:
Industry Practice Payment Details and Resubmission Details API Reference [REST][NVP]
When you submit payments, distinguish between the first transaction in the series, i.e., cardholder initiated transaction, and any subsequent merchant initiated payments in the series. You can do this using the transaction.source
field, where for the initial transaction, you must set transaction.source
=INTERNET
or any other allowable value to indicate that the transaction was initiated by the payer. For subsequent payments in the series, you must set transaction.source
=MERCHANT
to indicate that the transaction was initiated by you. Your payment service provider must have "MERCHANT" enabled as an allowable transaction source on your merchant acquirer link.
Transaction Source API Reference [REST][NVP]
When you submit the first cardholder initiated transaction or subsequent merchant initiated payments in a series, you must indicate to the gateway if the payment details are stored, not stored, or you intend to store them. For more information, see FAQs.
Recurring payment is an agreement where the payer authorizes you to process payments for recurring bills or invoices at agreed intervals (for example, weekly, monthly).
You can submit recurring payments for processing to the gateway if you have a payment agreement with the payer where the payer agrees for you to store their payment details for future use, and authorizes you to initiate subsequent recurring payments without their active participation.
To allow this, you need to provide the following fields in the initial transaction in the series:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET, and
sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
agreement.id
agreement.type
=RECURRING
For subsequent payments in a series that are initiated by you, you must provide
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=MERCHANT
sourceOfFunds.provided.card.storedOnFile
=STORED, and
agreement.id
: The same agreement.id as that provided in the initial transaction. This allows the gateway to link payments in a series.The following table specifies different scenarios or use cases to process a 3-D-Secure Authentication with cardholder initiated payments. For more information about the 3-D Secure authentication, refer to 3D-Secure Integration guide.
For external authorized transactions, please refer to Authentication guidelines.
The following fields are needed to have a successful recurring transaction when using WS API AUTHENTICATE_PAYER from version 61 request:
The following fields are needed to have a successful recurring transaction when using WS API AUTHENTICATE_PAYER from version 57-60 request:
Use Case | Integration Steps |
---|---|
Establish a recurring agreement with the payer that includes an initial charge and initiate a new series of recurring payments. |
|
Establish a Recurring Payment Series when No Payment is Due Initially If you want to establish a recurring payment series with the payer where there is no payment due at the moment the payer signs up for the service. Example: Monthly subscription services with no payment required when the customer signs up. |
When referring to the Authentication guidelines, use these additional parameters specified in the following steps to integrate 3DS for recurring payments. Steps 1 and 2 must be completed while the cardholder is in session. Step 3 should be used when you are ready to process the payment.
While the cardholder is in session, complete steps 1 and 2. When you are ready to process the payment use step 3. Step 1: Initiate Authentication
Step 2: Authenticate Payer
Step 3: Perform the verify operation and then choose one of the following options:
or
|
Add Card without establishing a Payment Agreement If you want to provide an option for payers to add their card details while creating their profile or accounts without having a payment agreement in place at the time of sign up. The added card can be used in the future. |
When referring to the Authentication guidelines, use these additional parameters specified in the following steps to integrate 3DS. Step 1: Initiate Authentication
Step 2: Authenticate Payer
|
Installment payment is an agreement where the payer authorizes the payment for a single purchase to be split into a number of payments processed at agreed intervals. For example, pay for a purchase in six monthly installments.
You can submit installment payments for processing to the gateway if you have a payment agreement with the payer where the payer agrees for you to store their payment details for future use, and authorizes you to initiate subsequent installment payments without their active participation.
To allow this, you need to provide the following fields in the initial transaction in the series:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET
sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
agreement.id, and
agreement.type
=INSTALLMENT
For subsequent installment payments in a series that are initiated by you, you must provide:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=MERCHANT
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.Unscheduled payment is an agreement where the payer authorizes the merchant to automatically deduct funds for a payment for an agreed purchase when required (unscheduled). For example, auto top-ups when the account value falls below a threshold.
You can submit unscheduled payments for processing to the gateway if you have a payment agreement with the payer where the payer agrees for you to store their payment details for future use, and authorizes you to initiate subsequent unscheduled payments without their active participation.
To allow this, you need to provide the following fields in the initial transaction in the series:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=INTERNET
sourceOfFunds.provided.card.storedOnFile
=TO_BE_STORED
agreement.id, and
agreement.type
=UNSCHEDULED
For subsequent unscheduled payments in a series that are initiated by you, you must provide:
sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
=MERCHANT
sourceOfFunds.provided.card.storedOnFile
=STORED, and
agreement.id
: The same agreement.id as that provided in the initial transaction. This allows the gateway to link payments in a series.Hosted Checkout for Cardholder-Initiated Transaction (CIT) allows you to collect consent from the payer to store their payment details for subsequent payer-initiated transactions.
Ensure that the MSO has configured your merchant profile for the gateway tokenization.
Follow these steps to request a Hosted Checkout for CIT:
interaction.saveCardForCredentialOnFile=PAYER_INITIATED_PAYMENTS
.
Hosted Checkout provides the payer with the available payment options.
interaction.operation=PURCHASE
) transaction request with sourceOfFunds.provided.card.storedOnFile=TO_BE_STORED
and transaction.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.
RETRIEVE_ORDER
request.
transaction.payerConsentForStoringCardDetails=PAYER_INITIATED_PAYMENTS
. sourceOfFunds.token
. INITIATE_CHECKOUT
with interaction.tokens
containing the gateway tokeninteraction.saveCardForCredentialOnFile=PAYER_INITIATED_PAYMENTS
- This allows the payer to enter new card details and store them.
Hosted Checkout displays the available payment options to the payer.
Hosted Checkout for Merchant-Initiated Transaction (MIT) allows you to collect consent from the payer to store their payment details for subsequent merchant-initiated transactions.
Follow these steps to request a Hosted Checkout for MIT:
INITIATE_CHECKOUT
with agreement.type
and agreement.id
Hosted Checkout provides the payer with the debit or credit payment options.
If the payer proceed with giving consent, then the hosted checkout will submits the transaction request with the following values:
sourceOfFunds.provided.card.storedOnFile=TO_BE_STORED
transaction.payerConsentForStoringCardDetails=MERCHANT_INITIATED_PAYMENTS
RETRIEVE_ORDER
request for a successful transaction:
transaction.payerConsentForStoringCardDetails=MERCHANT_INITIATED_PAYMENTS.
You can submit merchant initiated payments that are submitted in the context of certain industry practices for processing to the gateway if you have a payment agreement with the payer where the payer agrees for the merchant to store their payment details for future use, and authorizes you to initiate subsequent merchant payments without the payer's active participation.
To allow this, provide the following fields in the initial transaction in the series:
order.id
= "OD12345"transaction.id
= "TRAN 1"sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
= INTERNET
sourceOfFunds.provided.card.storedOnFile
= TO_BE_STORED
For subsequent merchant payments that you initiate, provide the following fields:
order.id
= "OD45678"
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, NO_SHOW_PENALTY, PARTIAL_SHIPMENT}
referenceOrderId
= "OD12345"
transaction.acquirer.traceid
= "MCC123456889"
You can resubmit a merchant initiated payment where previous authorization payment has failed due to insufficient funds. The operations to be resubmitted must be only Authorize or Pay.
To allow this, provide the following fields in the initial transaction in the series:
order.id
= "OD12345"transaction.id
= "TRAN 1"sourceOfFunds.type
=CARD
or SCHEME_TOKEN
sourceOfFunds.provided.card.*
fields or sourceOfFunds.token
transaction.source
= INTERNET
sourceOfFunds.provided.card.storedOnFile
= TO_BE_STORED
For subsequent merchant payments that you initiate, provide the following fields:
For reference, the first MIT transaction is referred to as MIT1 and the resubmitted MIT transaction is referred to as MIT2 afterwards in this section.
For MIT1, provide the following fields:
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, NO_SHOW_PENALTY, PARTIAL_SHIPMENT}
referenceOrderId
= "OD12345"
transaction.acquirer.traceid
= "MCC0987335353"
MIT 1 will decline due to insufficient funds. Hence, the merchant resubmits the sent MIT transaction, which is now MIT2.
For MIT 2, provide the following fields:
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, NO_SHOW_PENALTY, PARTIAL_SHIPMENT}
transaction.resubmission
="true"
referenceOrderId
= "OD12345"
transaction.acquirer.traceid
= "MCC0987335353"
To comply with the card scheme standards for processing cardholder initiated and merchant initiated transactions, you must indicate to the gateway if the payment details are stored, not stored, or you intend to store them using the sourceOfFunds.provided.card.storedOnFile
field.
For the initial transaction, that is, the cardholder initiated transaction:
sourceOfFunds.provided.card.storedOnFile
field.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: For subsequent payments, either a cardholder initiated transaction where the payer's stored payment details are used or for merchant initiated transactions using the stored payment details, set sourceOfFunds.provided.card.storedOnFile
=STORED
With gateway tokenization, the gateway sets the default values on your behalf.
sourceOfFunds.provided.card.storedOnFile
=NOT_STORED
sourceOfFunds.provided.card.storedOnFile
equal to the value provided by you in the transaction request. You can provide TO_BE_STORED
or NOT_STORED
in the customer initiated transaction.
sourceOfFunds.provided.card.storedOnFile
=STORED
Stored on File API Reference [REST][NVP]
If you do not have a unique identifier for your agreement with the payer you can:
If at the time of establishing a payment agreement with the payer, you do not intend to charge the payer, for example, if it's 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 cardholder initiated transaction in the series. For any subsequent payments, use the agreement.id
to link payments in the series.
If the payer has been authenticated using 3D-Secure authentication in MPGS, you can provide the authentication.transactionId
used in the original transaction.
For externally authenticated transactions, Please see the Implementing a 3DS Integration using the Authentication API page and navigate to section Options > Submit a Pre-Authenticated Payment Request.
The payment details against an agreement may change, for example, if:
If card details have changed (except in case of reissue of expired card and card scheme tokens), you must perform a cardholder initiated transaction using the same Agreement ID to update the payment details or gateway token before performing a merchant initiated transaction with the new card number. Depending on your business model, you may choose to create a new agreement.
If using a scheme token, the card number stored against the scheme token may automatically be updated by the scheme.
Copyright © 2023 Mastercard