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 use them to process future payments for payers. If so, you must provide information to the gateway in the initial transaction that you are storing payment details and intend 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 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
  • 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 DirectAPI v54 onwards:

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
  • 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
  • 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, or
  • 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 as a Recurring, Installment or Unscheduled payment. 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, you will need to 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.

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
  • 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
  • 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, i.e., 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=TO_BE_STORED
  • 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 such 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.

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
  • 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/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 © 2020 Commonwealth Bank of Australia