Credentials on File (API)

The process of storing credentials for future use is known as Credentials on File (CoF).
Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use, and that these must be flagged at the time of the first authorisation, by submitting the credentialsonfile field in your requests.
You must also flag any subsequent payments that are utilising previously-stored credentials, by including the credentialsonfile field in these requests.
Examples of situations where the CoF mandate applies:
- Processing an account check or authorisation request, where card details are to be re-used later.
- Processing a re-authorisation.
- Processing regular recurring payments.

Requests processed before the cut-off are not affected, but new requests after the cut-off must include the credentialsonfile field.

Benefits
Identifying transactions as using CoF provides the following advantages:
- Increases the likelihood of transaction authorisation and settlement.
- Greater transparency and improved experience from the customer’s perspective.
- Issuers are less likely to use the absence of a security code as a reason to decline a transaction.
Initial payment request including CoF
Update the payload submitted within your JWT (for AUTH and ACCOUNTCHECK request types) to include the additional field, credentialsonfile, with value set to “1”:
"credentialsonfile": "1"


Customer Initiated Transactions using previously-stored credentials
Transactions processed by the customer are called Customer Initiated Transactions (CIT).
Update the request submitted using our Webservices API to include the additional field, credentialsonfile, with value set to “2”:
"credentialsonfile": "2"

Processing Merchant Initiated Transactions
Transactions processed by the merchant are called Merchant Initiated Transactions (MIT).
Visa mandate that you must provide a reason for processing MIT.

This is achieved by submitting a new field in the AUTH request (submitted using our Webservices API) called initiationreason, containing a single character that maps to a reason as to why the payment is being processed.
These are the values we currently support:
- “A” – Re-authorisation
- “C” – Unscheduled payment
- “D” – Delayed Charges
- “S” – Resubmission
- “X” – No-show (for a hotel booking)
Click here for further information on the different initiationreason values.


Processing MIT using previously-stored credentials
In the AUTH request submitted using our Webservices API, include the field initiationreason, setting the value to be one of those listed above.
"initiationreason": "S"

The MIT initiation reasons do not apply to transactions regarded as Customer Initiated Transactions (CIT).
Examples of using CoF and MIT in requests
Please refer to the table below for example use-cases of the CoF and MIT fields to be included when processing transactions:
Use case | CoF value | MIT value |
First payment in a sequence of recurring payments | 1 | Don’t send |
Payment where card details are to be stored for future payments | 1 | Don’t send |
Previously-agreed regular subscription payments | 2 | Don’t send |
Customer requests that funds are added to their account | 2 | Don’t send |
Re-authorisation initiated by the customer | 2 | Don’t send |
Re-authorisation initiated by the merchant | 2 | A |
Unscheduled payment initiated by the merchant | 2 | C |
Delayed charge from stored credentials, initiated by the merchant | 2 | D |
Re-submission of payment, initiated by the merchant | 2 | S |
No-show payment, initiated by the merchant | 2 | X |