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.
You can choose to store payment details in your own application, or use gateway tokenization or use card scheme tokens.

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

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:

  • products or services that require you to charge a payer using a predefined schedule, e.g., subsequent recurring payment for a magazine subscription, gym membership
  • payers to pay for a single purchase in several installments, or
  • offer the payer a service to charge them on demand for services, e.g., account top-ups when the amount available falls below a defined threshold.

In such cases, you will need to enter into an agreement with the payer about these services. The payer must agree for you store their payment details for this purpose and allow you to subsequently initiate payments with the stored payment details without their active participation.

Agreement Details

When you enter an agreement with the payer that allows you to subsequently submit merchant initiated payments, you need to provide the following agreement details in the initial transaction in the series, i.e., the cardholder initiated transaction:

  • agreement.id: 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, i.e., in the cardholder initiated transaction.
Agreement ID and Type are not required to be submitted if you only intend to process cardholder initiated transactions with stored payment details.

Agreement 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.

Recurring Payments

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.

Authenticating the Payer

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:

  • agreement.id
  • agreement.type=RECURRING
  • agreement.numberOfPayments
  • agreement.amountVariability
  • agreement.expiryDate
  • agreement.paymentFrequency
  • agreement.minimumDaysBetweenPayments

The following fields are needed to have a successful recurring transaction when using WS API AUTHENTICATE_PAYER from version 57-60 request:

  • agreement.id
  • agreement.type=RECURRING
  • agreement.expiryDate
  • agreement.recurring.daysBetweenPayments
Use Case Integration Steps

Establish a recurring agreement with the payer that includes an initial charge and initiate a new series of recurring payments.

  • Perform Authentication as described in the Authentication guidelines and specify the amount required for the initial payment.

  • Follow the steps mentioned in the Cardholder Initiated Payments section, and then use option 1 if you are processing your 3-D Secure with the payment gateway, otherwise use option 2.

    • Option1: Link the authentication.transactionID from the authentication steps.

      • or

    • Option2: Supply 3D Secure data from a third-party.

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

  • authentication.purpose=ADD_CARD or MAINTAIN_CARD

Step 2: Authenticate Payer

  • Amount= 0

  • agreement.type

    For more information about agreement.type, refer to section agreement.type.

  • agreement.expiryDate

  • agreement.minimumDaysBetweenPayments

Step 3: Perform the verify operation and then choose one of the following options:

  • Link the authentication.transactionID

    Ensure that you provide the same agreement.* details as provided in Step 1.

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

  • authentication.purpose= ADD_CARD or MAINTAIN_CARD

Step 2: Authenticate Payer

  • Amount= 0

Performing Merchant Initiated Installment Payments

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.

Performing Merchant Initiated Unscheduled Payments

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.

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.

Copyright © 2022 Mastercard