Credential on File, Cardholder, and Merchant Initiated Transactions

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

• greater visibility of transaction risk levels for issuers
• higher authorization approval rates and completed sales, and
• improved payer experience.

The gateway supports the following payments using stored payment details from the WS API v74 onwards:

• Cardholder Initiated Payments
• Merchant Initiated Recurring Payments
• Merchant Initiated Installment Payments
• Merchant Initiated Unscheduled Payments
• Merchant Initiated Industry Practice Payments and Resubmission

Credential on file with 3-D Secure

You can use 3-D Secure with Cardholder Initiated Payments. For further information, read the following specific details.

Performing Cardholder Initiated Payments

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.

Performing Merchant Initiated Payments

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

• Recurring Payment - The products or services that require you to charge a payer using a predefined schedule.For example, subsequent recurring payment for a magazine subscription or a gym membership.
• Installments - Payer to pay for a single purchase in several installments.
• Top-ups - Offer the payer a service to charge them on demand for services. For example, account top-ups when the amount available falls below a defined threshold.

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

• Related/Delayed Charge - An additional account charge after the payment for the initial services has already been processed. For example, an additional mini-bar charge after the cardholder has checked out of a hotel.
• No Show Penalty - A penalty charged to the payer according to the merchant’s cancellation policy. For example, a cardholder’s cancellation of a reservation without providing proper advance notice to the merchant.
• Partial Shipment - A shipment where the merchant decides to ship the goods from the same order in multiple shipments due to various reasons such as goods unavailability, involvement of multiple suppliers for goods, and so on. For example, the supplier does not have all the goods or logistics available.

Resubmission Payment use case

• Resubmission - A previous attempt to obtain an Authorization for a transaction declines, but the issuer’s response does not prohibit the merchant from trying again later, even when the payer is no longer present. For example, Insufficient funds.

Agreement Details

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]

Industry Practice Payment Details and Resubmission Details

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:
  • an industry practice payment: this is the reference to the initial cardholder initiated transaction.
  • a resubmission transaction: this is the reference to the merchant initiated transaction that is being resubmitted.

Industry Practice Payment Details and Resubmission Details API Reference [REST][NVP]

Transaction Source

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.

Performing Merchant Initiated Industry Practice 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, MOTO, MAIL_ORDER, TELEPHONE_ORDER, CALL_CENTRE, or VOICE_RESPONSE
• 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"
• transaction.relatedTransactions.firstTransactionInTheSeries.source = MOTO, MAIL_ORDER, TELEPHONE_ORDER, CALL_CENTRE, or VOICE_RESPONSE

Performing Merchant Initiated Resubmission Payments

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"
In case of resubmission of MIT, it is recommended for Merchants to use the same order.id as in MIT 1, but a new transaction.id as gateway does not allow duplicate transaction.id.
• 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"

Hosted Checkout for Cardholder-Initiated Transaction

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.

Prerequisite

• Ensure that the MSO has configured your merchant profile for the gateway tokenization.
• To use the Credential On File functionality, WS API v74 or above must be used.

Request a Hosted Checkout for CIT

Follow these steps to request a Hosted Checkout for CIT:

1. Request a WS API INITIATE_CHECKOUT with interaction.saveCardForCredentialOnFile=PAYER_INITIATED_PAYMENTS.

   Hosted Checkout provides the payer with the available payment options.

   The payer's list of payment options does not include Click to Pay.

   The payer's list of payment options does not include Click to Pay.
2. If the payer selects 'Debit or Credit', the following Payment options checkbox displays.

   

   If the payer pays with a method other than a credit card, such as ACH or PayPal, the standard checkout procedure applies. Hosted Checkout does not display or link to the Terms and Conditions, Privacy Policies, or both. It is your responsibility to provide these details to the payer as required by any regulatory regulations or privacy laws
3. 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.
   1. If the payer proceeds to pay without giving consent, the payment process works as usual. In this case, the gateway will not tokenize the payer's card.
   2. If the payer proceeds to pay with giving consent, then the Hosted Checkout;
      1. Sets the correct Card On File Indicator
      2. Submit the AUTH (if interaction.operation=AUTHORIZE) 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.

4. After the gateway returns the payer to your store's website, submit a WS API RETRIEVE_ORDER request.
   1. For a successful transaction:
      1. If the payer has provided consent, the response will contain the information that consent was provided in the field transaction.payerConsentForStoringCardDetails=PAYER_INITIATED_PAYMENTS.
      2. If the payer has provided consent and the transaction was successful, the response will contain the gateway token in the field sourceOfFunds.token.
5. For subsequent cardholder-initiated payment,
   1. Request WS API INITIATE_CHECKOUT with interaction.tokens containing the gateway token
   2. interaction.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.

6. If the payer selects 'Debit or credit', the details for the token are listed and the payer can choose to pay with the token.

   

Hosted Checkout for Merchant-Initiated Transaction

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.

Prerequisite

• Ensure that the MSO has configured your merchant profile for the gateway tokenization.
• Merchants can create payer accounts and save the token information against those accounts.
• To use the Credential On File functionality, WS API v74 or above must be used.

Request a Hosted Checkout for MIT

Follow these steps to request a Hosted Checkout for MIT:

1. Request a WS API INITIATE_CHECKOUT with agreement.type and agreement.id

   Hosted Checkout provides the payer with the debit or credit 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 gateway token.
2. The payer can proceed forward only by giving consent, that is, by selecting the checkbox. The pay button is disabled until they check the box.

   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
   You must ensure that the payer complies 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.
3. After the gateway returns the payer to your store's website, submit a WS API RETRIEVE_ORDER request for a successful transaction:
   1. If the payer has provided consent, the response will contain the information transaction.payerConsentForStoringCardDetails=MERCHANT_INITIATED_PAYMENTS.
      It is the responsibility of the merchant to ensure that items that do not need agreements are not included in the order or transaction.
   2. If the payer has not provided consent, the payer cannot proceed (cart abandonment).

FAQs

How do I indicate to the gateway if the payment details are stored, not stored, or I intend to store them?

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:

• if it's a one-off payment, i.e., you do not intend to store payment details, you can omit the sourceOfFunds.provided.card.storedOnFile field.
• if it's a payment where you intend to store payment details 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 where you store the payment details — your own application (requires you to be PCI-compliant), or gateway tokenization, or card scheme tokens.
  • irrespective of the whether you store the payment details before or after submitting the transaction to the gateway.

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.

• When you are not enabled for tokenization, the gateway sets sourceOfFunds.provided.card.storedOnFile=NOT_STORED
• When you tokenize the card details, the gateway sets 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.
• When you perform subsequent transactions using the gateway token, the gateway sets sourceOfFunds.provided.card.storedOnFile=STORED

Stored on File API Reference [REST][NVP]

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 cardholder initiated transaction.
• Use an existing identifier (that you are already storing in your system), for example, the order ID for the first payment in the series.

Do I need to submit a payment when establishing the payment agreement?

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.

What if the PAN for an agreement changes?

The payment details against an agreement may change, for example, if:

• the payer lost their card and was issued a new card
• the payer changed their bank, and
• the 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 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.