Table of Contents
Overview
This article will discuss the best practices for using Credential on File with the Payment API (Collect.js and Gateway.js) and recurring transactions. Please note that if you're in a country which falls under the PSD2 mandate, and are required to perform 3-D Secure (3DS), you will need to use Gateway.js. For countries that are not required to use 3DS, following this process will help mitigate risk of recurring transactions not being approved.
Each transaction will need to include Credential on File (CoF) variables. The variables will depend on what type of transaction is being preformed.
Initial Transaction
When performing a "first store" transaction (i.e. the first time this customer vault entry is being created/stored for future use), you will need to flag the transaction appropriately. If you are using Collect.js without 3DS, you will just need to create a Payment Token, as usual.
If you are using Collect.js with Gateway.js (3DS), you must ensure that a step up is mandated. You will do this by passing challengeIndicator
, with a value of 04
.
After submitting the Collect.js request a Payment Token, will be returned to be used with the Payment API. If Gateway.js (3DS) was used, there will also be 3DS variables in the response. These will need to be included in the Payment API request.
This will need to be passed in the 'options' parameter (See below example).
CollectJS.configure({ callback: (e) => const options = { paymentToken: e.token, currency: 'USD', amount: '1000', email: 'none@example.com', phone: '8008675309', city: 'New York', state: 'NY', address1: '123 Fist St.', country: 'US', firstName: 'John', lastName: 'Doe', postalCode: '60001', challengeIndicator: '04' // Only necessary for 3DS transactions } });
Payment API Transaction Request
When sending the Payment API request you will want to include the Credential on File variables, Payment Token and if you are using 3DS, you must include the variables that were returned in the Gateway.js request.
After submitting the initial transaction, you will want to store the transaction_id
that is returned. This will need to be provided in subsequent transactions.
Please note that the billing_method
variable is not required if using CoF for Unscheduled Subsequent transactions.
- Add Customer Vault Entry
-
customer_vault
set toadd_customer
-
-
billing_method
set torecurring
-
initiated_by
set tocustomer
-
stored_credential_indicator
set tostored
POST: /api/transact.php security_key: '2jPu***************jkp1' type: 'sale' amount 123.00' payment_token: {INSERT_PAYMENT_TOKEN} billing_method: 'recurring' customer_vault: 'add_customer' stored_credential_indicator: 'stored' initiated by: 'customer' // If using Gateway.js/3DS, you will need to include the variables that were returned cavv: {INSERT_CAVV} xid: {INSERT_XID} eci: {INSERT_ECI} cardHolderAuth: {INSERT_CARDHOLDERAUTH} threeDsVersion: {INSERT_THREEDSVERSION} directoryServerId: {INSERT_DIRECTORYSERVERID}
Subsequent Transactions
When performing subsequent transactions, there is no need to mandate a step-up. It will only be for the first-store.
Subsequent transactions will be broken down into two categories. The first one being a Customer Initialed Transaction (CIT). This is a transaction that will be initiated by the customer. The second one is a Merchant Initiated Transaction (MIT), which is initiated by the merchant. Each type will have a slightly different request.
Customer Initiated Transaction
A subsequent transaction that is initiated by the customer will need to include the appropriate flags. If you are in a country that requires 3DS, you will not need to indicate a specific challengeIndicator
. This will default to a value of 01
. Please note that Customer Initiated transactions will require that 3DS variables are included in the response.
In the Payment API Transaction Request you will want to include:
-
customer_vault_id
set to the customer's ID -
billing_method
set torecurring
-
initiated_by
set tocustomer
-
stored_credential_indicator
set toused
-
initial_transaction_id
set to thetransaction_id
that was returned in the first-store transaction
POST: /api/transact.php security_key: '2jPu*****************jkp1' type: 'sale' amount: '123.00' customer_vault_id: {INSERT_CUSTOMER_ID} billing_method: 'recurring' stored_credential_indicator: 'used' initiated by: 'customer' initial_transaction_id: {INSERT_INITIAL_TRANSACTION_ID}
//If using Gateway.js/3DS, you must include the 3DS variables that are returned.
cavv: {INSERT_CAVV}
xid: {INSERT_XID}
eci: {INSERT_ECI}
cardHolderAuth: {INSERT_CARDHOLDERAUTH}
threeDsVersion: {INSERT_THREEDSVERSION}
directoryServerId: {INSERT_DIRECTORYSERVERID}
Merchant Initiated Transaction
A subsequent transaction that is initiated by the merchant will need to include the appropriate flags. It is also important to note that a merchant initiated transaction should not use any 3DS. This is because the customer is not available to validate the 3DS challenge.
In the Payment API Transaction Request you will want to include:
-
customer_vault_id
set to the customer's ID -
billing_method
set torecurring
-
initiated_by
set tomerchant
-
stored_credential_indicator
set toused
-
initial_transaction_id
set to thetransaction_id
that was returned in the first-store transaction
POST: /api/transact.php security_key: '2jPu*****************jkp1' type: 'sale' amount: '123.00' customer_vault_id: {INSERT_CUSTOMER_ID} billing_method: 'recurring' stored_credential_indicator: 'used' initiated by: 'merchant' initial_transaction_id: {INSERT_INITIAL_TRANSACTION_ID}