Loading...
In this guide, you’ll learn how to correctly pass Credential on File (COF) data for the following use cases:
Each use case involves an initial CIT where the customer transacts with the merchant and agrees to store their card (customer signup). Depending on the use case, the customer might also consent to an installment/subscription or agree that their card can be charged without their direct involvement. So, first we’ll cover that initial step and then go into each specific use case.
The following table summarizes the required data for each use case.
| Data | First Transaction / Customer Signup | Subsequent Transaction: One-Click Checkout | Subsequent Transaction: Recurring or Installment | Subsequent Transaction: Auto Account Top-Up |
|---|---|---|---|---|
| Model | UNSCHEDULED | UNSCHEDULED | RECURRING or INSTALLMENT | UNSCHEDULED |
| Initiator | PAYER | PAYER | MERCHANT | MERCHANT |
| Sequence | FIRST | SUBSEQUENT | SUBSEQUENT | SUBSEQUENT |
| Brand Reference | N/A | N/A | Required | Required |
COF is a way of identifying stored card transactions. The location of the stored card details doesn't matter — the details could be held in our Card Storage solution or stored securely by the merchant or by a third party for merchant use.
The purpose of the COF mandate from the card schemes, such as Visa or Mastercard, is to help reduce fraud by requiring merchants to include certain fields in the authorization message when using a customer’s stored credentials for payments. These COF fields indicate to issuers and acquirers that the merchant has a prior arrangement with the customer to store their card details and potentially to make subsequent payments on their behalf. This benefits the merchant and cardholder by identifying a more trusted transaction, which can enable scenarios like one-click checkout or recurring transactions.
Transactions using stored card details are either customer-initiated (payer) (CIT) or merchant-initiated (MIT).
The following table describes the relevant COF data and fields.
| Field Name / Data | Description |
|---|---|
| Initiator | The initiator of the transaction. Allowed values: PAYER - Indicates a transaction that is customer-initiated (CIT). MERCHANT - Indicates a transaction that is merchant-initiated (MIT). |
| Model | The relationship type the customer agreed to with the merchant and the category of transaction being processed. Allowed values: RECURRING - Payment with no fixed duration that continues until the customer cancels. INSTALLMENT - Payment of an agreed amount on the same day each month until the fixed duration ends. UNSCHEDULED - Oneoff payment with no fixed duration. |
| Sequence | Indicates the stage of card storage. Allowed values: FIRST SUBSEQUENT |
| Brand Reference | Also referred to as Scheme Reference Data (SRD). A unique identifier provided by a card scheme, such as Visa or Mastercard, that links to the payment history between the customer and merchant. Also referred to as Transaction ID or Trace ID, depending on the card scheme. This will appear in the response message of an initial transaction. |
The first transaction is a CIT. For example, the customer is making a payment on the merchant’s website for the first time or choosing a subscription or installment product. With this in mind, the model needs to match the agreement that the customer is signing up for. In our example, it’s Unscheduled, but it could be Installment or Recurring.
For this transaction, initiator and sequence will always be Payer and First, respectively.
If future transactions using this stored card are merchant-initiated (MITs), the first transaction must include 3D Secure 2 payment authentication with the Challenge Mandated flag passed to the Issuer. You must also store the brand references for future transactions. For more information, see our Merchant-Initiated Transactions article.
{
"id": "TRN_wyU5fw3aUJZZXZ9OzdxHhLYete9tYk_14406011",
"time_created": "2022-05-20T14:18:05.428Z",
"type": "SALE",
"status": "CAPTURED",
"channel": "CNP",
"capture_mode": "AUTO",
"amount": "100",
"currency": "EUR",
"country": "IE",
"merchant_id": "MER_c4c0df11039c48a9b63701adeaa296c3",
"merchant_name": "Sandbox_merchant_2",
"account_id": "TRA_6716058969854a48b33347043ff8225f",
"account_name": "Transaction_Processing",
"reference": "14406011",
"payment_method": {
"result": "00",
"message": "[ test system ] AUTHORISED",
"entry_mode": "ECOM",
"authentication": {
"cavv_result": ""
},
"card": {
"brand": "VISA",
"masked_number_last4": "XXXXXXXXXXXX5262",
"authcode": "12345",
"brand_reference": "ef5FXsbbtJfXKhh0",
"brand_time_created": "",
"provider": {
"result": "00",
"cvv_result": "M",
"avs_address_result": "M",
"avs_postal_code_result": "M"
}
}
},
"batch_id": "BAT_1092561",
"action": {
"id": "ACT_wyU5fw3aUJZZXZ9OzdxHhLYete9tYk",
"type": "AUTHORIZE",
"time_created": "2022-05-20T14:18:05.428Z",
"result_code": "SUCCESS",
"app_id": "i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR",
"app_name": "demo_app"
}
}In our code samples, we use a stored card / payment method (also known as a token), but a merchant might store the card data themselves or use a third party.
This use case is a CIT. For example, the customer returns to the merchant’s website and is presented with their previously stored card. It is recommended to also capture the security code (CVV) and, depending on the region, perform 3D Secure 2 authentication.
Brand reference is not required for subsequent CITs.
{
"id": "TRN_G8Kj4BTiKOS67ywj9V3nbn5hLpet6f_53509251",
"time_created": "2022-05-20T16:43:27.568Z",
"type": "SALE",
"status": "CAPTURED",
"channel": "CNP",
"capture_mode": "AUTO",
"amount": "100",
"currency": "EUR",
"country": "IE",
"merchant_id": "MER_c4c0df11039c48a9b63701adeaa296c3",
"merchant_name": "Sandbox_merchant_2",
"account_id": "TRA_6716058969854a48b33347043ff8225f",
"account_name": "Transaction_Processing",
"reference": "53509251",
"payment_method": {
"result": "00",
"message": "[ test system ] AUTHORISED",
"entry_mode": "ECOM",
"authentication": {
"cavv_result": ""
},
"card": {
"funding": "CREDIT",
"brand": "VISA",
"masked_number_last4": "XXXXXXXXXXXX5262",
"authcode": "12345",
"brand_reference": "66CX0osxtpW7hPOG",
"brand_time_created": "",
"tag_response": "",
"cvv_result": "MATCHED",
"avs_address_result": "MATCHED",
"avs_postal_code_result": "MATCHED",
"avs_action": "",
"provider": {
"result": "00",
"cvv_result": "M",
"avs_address_result": "M",
"avs_postal_code_result": "M"
}
}
},
"batch_id": "BAT_1092561",
"action": {
"id": "ACT_G8Kj4BTiKOS67ywj9V3nbn5hLpet6f",
"type": "AUTHORIZE",
"time_created": "2022-05-20T16:43:27.568Z",
"result_code": "SUCCESS",
"app_id": "i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR",
"app_name": "demo_app"
}
}This use case is an MIT. For example, the merchant charges the customer’s card based on an agreed subscription or installment plan. You must supply the brand reference from the original authorization or verification when the card was first stored. When flagged correctly, MITs are deemed as out of scope for the European requirements for Strong Customer Authentication (SCA). For more information, see our Merchant-Initiated Transactions article.
In this example, we set the model to be Recurring, but we could also choose Installment.
{
"id": "TRN_xOPLdeWShj4YYqydi2Sn7HkQ3Gf3ZK_40424451",
"time_created": "2022-05-20T17:38:17.637Z",
"type": "SALE",
"status": "CAPTURED",
"channel": "CNP",
"capture_mode": "AUTO",
"amount": "100",
"currency": "EUR",
"country": "IE",
"merchant_id": "MER_c4c0df11039c48a9b63701adeaa296c3",
"merchant_name": "Sandbox_merchant_2",
"account_id": "TRA_6716058969854a48b33347043ff8225f",
"account_name": "Transaction_Processing",
"reference": "40424451",
"payment_method": {
"result": "00",
"message": "[ test system ] AUTHORISED",
"entry_mode": "ECOM",
"card": {
"brand": "VISA",
"masked_number_last4": "XXXXXXXXXXXX5262",
"authcode": "12345",
"brand_reference": "FB7P70xHebhcC7Rr",
"brand_time_created": "",
"provider": {
"result": "00",
"cvv_result": "M",
"avs_address_result": "M",
"avs_postal_code_result": "M"
}
}
},
"batch_id": "BAT_1092561",
"action": {
"id": "ACT_xOPLdeWShj4YYqydi2Sn7HkQ3Gf3ZK",
"type": "AUTHORIZE",
"time_created": "2022-05-20T17:38:17.637Z",
"result_code": "SUCCESS",
"app_id": "i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR",
"app_name": "demo_app"
}
}This use case is an MIT. For example, the merchant charges the customer’s card based on their account balance dropping below a certain threshold. In this case, we set the model to be Unscheduled. You must also supply the brand reference from the original authorization or verification when the card was first stored.
When flagged correctly, MITs are deemed as out of scope for the European requirements for SCA. For more information, see our Merchant-Initiated Transactions article.
{
"id": "TRN_J69gReLKy8dP1p5WgdVLLnX7xADx8y_01577731",
"time_created": "2022-05-20T17:43:28.196Z",
"type": "SALE",
"status": "CAPTURED",
"channel": "CNP",
"capture_mode": "AUTO",
"amount": "100",
"currency": "EUR",
"country": "IE",
"merchant_id": "MER_c4c0df11039c48a9b63701adeaa296c3",
"merchant_name": "Sandbox_merchant_2",
"account_id": "TRA_6716058969854a48b33347043ff8225f",
"account_name": "Transaction_Processing",
"reference": "01577731",
"payment_method": {
"result": "00",
"message": "[ test system ] AUTHORISED",
"entry_mode": "ECOM",
"card": {
"brand": "VISA",
"masked_number_last4": "XXXXXXXXXXXX5262",
"authcode": "12345",
"brand_reference": "0sJ211EAr8pEp7dy",
"brand_time_created": "",
"provider": {
"result": "00",
"cvv_result": "M",
"avs_address_result": "M",
"avs_postal_code_result": "M"
}
}
},
"batch_id": "BAT_1092561",
"action": {
"id": "ACT_J69gReLKy8dP1p5WgdVLLnX7xADx8y",
"type": "AUTHORIZE",
"time_created": "2022-05-20T17:43:28.196Z",
"result_code": "SUCCESS",
"app_id": "i9R0byBBor6RqTQNj3g4MuVBwH5rd7yR",
"app_name": "demo_app"
}
}