Credential on File Information

Please note the below is meant to be a guide for how the platform supports CIT and MIT use cases. This is not meant to be an exhaustive list of items needed in order to be compliant. For more information on CIT/MIT compliance, please consult your processor.

Credential on File regulations apply any time data is stored to process future purchases for a cardholder.

Customer vs Merchant Initiated

When a customer is actively engaged in checkout - either physically present in a store, or checking out online in their browser, that is a Customer Initiated Transaction (CIT).

When the customer isn’t actively engaged, but has given permission for their card to be charged, that is a Merchant Initiated Transaction (MIT). In order for a merchant to submit a Merchant Initiated Transaction, a Customer Initiated transaction is required first.

Overview

A cardholder’s consent is required for the initial storage of credentials. When a card is stored, an initial transaction should be submitted (Validate, Sale, or Auth) with the correct credential-on-file type. The transaction must be approved (not declined or encounter an error.) Then, store the transaction ID of the initial customer initiated transaction. The transaction ID must then be submitted with any follow up transactions (MIT or CIT.)

Credential on File types include Recurring, Installment, and Unscheduled types.

For simplicity - we are using the Payment API variables. These match the names of the Batch Upload, Collect.js, Browser Redirect, or the Customer-Present Cloud APIs. The Three-Step API follows the same pattern, and the variables should be submitted on Step 1.

Request Details

Variable	Description
initiated_by	Who initiated the transaction. Values: ‘customer’ or ‘merchant’
initial_transaction_id	Original payment gateway transaction id.
stored_credential_indicator	The indicator of the stored credential. Values: ‘stored’ or ‘used’ Use ‘stored’ when processing the initial transaction in which you are storing a customer’s payment details (customer credentials) in the Customer Vault or other third-party payment storage system. Use ‘used’ when processing a subsequent or follow-up transaction using the customer payment details (customer credentials) you have already stored to the Customer Vault or third-party payment storage method.

Response Details

Variable	Description
cof_supported	Credential on File support indicator specific to the transaction. Values: ‘stored’ or ‘used’ Value will be ‘stored’ if CIT/MIT transaction was sent to a processor that supports the feature. Value will be ‘used’ if CIT/MIT transaction was sent to a processor that does not support the feature or if a merchant-initiated transaction cannot occur due to Cross-Processor limitations.

Please Note: For Three-Step Redirect transactions, the request details must be sent in Step 1 and the ‘cof-supported’ element will be returned in the response of Step 3.

Referencing the Initial Transaction:

When doing a credential-on-file type transaction, we will reject any follow up transactions that pass in a card number that does not match the card brand used in the initial transaction. For example, using a Mastercard when the original transaction uses Visa will result in the transaction getting rejected. The card brands each have independent systems for tracking card-on-file transactions, so an initial transaction ID cannot be reused between them. We reject this type of incorrect reuse at the time of the request because it can result in settlement failures, downgrades, etc. later.

If a customer changes their card on file, a good practice is to first store it as a new initial transaction, and reference that initial transaction ID for future payments on the new card.

Recurring:

A transaction in a series of transactions that uses a stored credential and are processed at fixed, regular intervals (not to exceed one year between transactions), and represents cardholder agreement for the merchant to initiate future transactions for the purchase of goods or services provided at regular intervals.

If a customer is signing up for a recurring subscription, the merchant is expected to send “an initial recurring transaction” every time the customer signs up for a new recurring subscription.

For an initial transaction:

• For a free trial, the initial transaction will be a validate transaction type (or auth if validate is not supported.)
• If the customer is being charged immediately for a product, the initial transaction will be a sale or an authorization for the correct amount.

Either transaction MUST INCLUDE three items:

• billing_method=recurring
• initiated_by=customer
• stored_credential_indicator=stored

Examples

Example 1: In this request, an initial recurring sale is sent and an approved transaction is returned in the response. Store this transaction for the follow up request.

Request	…type=sale&billing_method=recurring&initiated_by=customer&stored_credential_indicator=stored…
Response	…response=1&responsetext=Approved&transactionid=1234567890…

The transaction ID would be stored and submitted on follow up transactions. The follow up transaction(s) would include:

• billing_method=recurring
• initiated_by=merchant
• stored_credential_indicator=used
• initial_transaction_id=XXXXXXXXXX

Example 2: In this request, the subsequent merchant initiated sale is processed using the stored transaction from Example 1.

Request	…type=sale&billing_method=recurring&initiated_by=merchant&stored_credential_indicator=used&initial_transaction_id=1234567890…
Response	…response=1&responsetext=Approved&transactionid=1234567891…

Please Note: This transaction ID cannot be used for “unscheduled” or “installment” credential-on-file transactions.

Installment:

An “installment” transaction is a series of transactions that uses a stored credential and represents cardholder agreement with the merchant to initiate one or more future transactions over a period of time for a single purchase of goods or services.

Installment transactions work just like Recurring in that you need a customer initiated transaction for a subsequent installment transaction. The difference is the billing_method will be “installment”.

The customer initiated transaction MUST INCLUDE at least three items (* recommended to send, if available):

• billing_method=installment
• initiated_by=customer
• stored_credential_indicator=stored
• * billing_total
• * billing_number (Values: 0-99)

Examples

Example 3: In this request, an initial installment sale is sent and an approved transaction is returned in the response. Store this transaction for the follow up request.

Request	…type=sale&billing_method=installment&initiated_by=customer&stored_credential_indicator=stored&billing_total=100.00&billing_number=1&amount=25.00…
Response	…response=1&responsetext=Approved&transactionid=1234567890…

The transaction ID would be stored and submitted on follow up transactions. The follow up transaction(s) would include (* recommended to send, if available):

• billing_method=installment
• initiated_by=merchant
• stored_credential_indicator=used
• initial_transaction_id=XXXXXXXXXX
• * billing_total
• * billing_number

Example 4: In this request, the subsequent merchant initiated sale is processed using the stored transaction from Example 3.

Request	…type=sale&billing_method=installment&initiated_by=merchant&stored_credential_indicator=used&initial_transaction_id=1234567890&billing_total=100.00&billing_number=1&amount=25.00…
Response	…response=1&responsetext=Approved&transactionid=1234567891…

Please Note: This transaction ID cannot be used for “unscheduled” or “recurring” card on file transactions.

Unscheduled Credential On File:

For payments that aren’t recurring or installment - there are unscheduled options as well.

The first customer initiated transaction will include these two items (no billing method):

• initiated_by=customer
• stored_credential_indicator=stored

Examples

Example 5: In this request, an initial unscheduled sale is sent and an approved transaction is returned in the response. Store this transaction for the follow up request.

Request	…type=sale&initiated_by=customer&stored_credential_indicator=stored…
Response	…response=1&responsetext=Approved&transactionid=1234567890…

The transaction ID can be used, without a billing method, for a customer initiated or merchant initiated transaction.

Please Note: The transaction ID cannot be used for a “recurring” or “installment” transaction.

Unscheduled, Customer Initiated: A card-absent transaction initiated by the cardholder where the cardholder does not need to enter their card details as the merchant uses the payment credential previously stored by the cardholder to perform the transaction. Examples include a transaction using customer’s merchant profile or digital wallet.

This is your typical shopping cart scenario where the customer checks out without having to re-enter their card details.

The follow up transaction(s) would include:

• initiated_by=customer
• stored_credential_indicator=used

Example 6: In this request, a subsequent unscheduled sale is sent and an approved transaction is returned in the response.

Request	…type=sale&initiated_by=customer&stored_credential_indicator=used…
Response	…response=1&responsetext=Approved&transactionid=1234567891…

Unscheduled, Merchant Initiated: A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date, where the cardholder has provided consent for the merchant to initiate one or more future transactions. An example of this transaction is an account auto-top up transaction.

An example of an account auto-top up would be a customer with an account with a balance. When that balance gets low, the customer’s card is charged automatically, without the customer’s involvement.

The follow up transaction(s) would include:

• initiated_by=merchant
• stored_credential_indicator=used
• initial_transaction_id=XXXXXXXXXX

Example 7: In this request, a subsequent unscheduled sale is sent and an approved transaction is returned in the response.

Request	…type=sale&initiated_by=merchant&stored_credential_indicator=used&initial_transaction_id=1234567890…
Response	…response=1&responsetext=Approved&transactionid=1234567892…

Appendix 1: Recommend Further Reading:

If there is any question where a transaction type falls, we recommend reviewing the official card brand documentation. Visa’s guidelines are the most stringent, and generally if you follow those guidelines, you’ll also be compliant for MasterCard, American Express and Discover.

Visa:
https://usa.visa.com/dam/VCOM/global/support-legal/documents/stored-credential-transaction-framework-vbs-10-may-17.pdf

MasterCard:
https://www.mastercard.us/content/dam/public/mastercardcom/na/us/en/banks-and-credit-unions/other/credential-on-file-the-digital-commerce-growth-engine.pdf