Contents

Credentials on File

 

PAYMENT
stored credential is information (including, but not limited to, an account number or payment token) that is stored in order to process future transactions.

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:

 

Calendar
This mandate came into effect on 30th April 2018.

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

Info
While this is only mandated by Visa and Mastercard, you can still submit these values in all your requests, and we will ignore them for other payment types.

 


 

Benefits

Identifying transactions as using CoF provides the following advantages:

 


 

Initial payment request

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"

 

Info
If the credentialsonfile field has been submitted in the request and it is supported by the acquirer processing the transaction, it is returned in the response JWT.
Warning
If the parent response indicates an error occurred (errorcode ≠ “0”), the credential cannot be considered a stored credential, and you must not use these card details in any subsequent payments.

 


 

Customer Initiated Payment (CIT) using previously-stored credentials

Update the request submitted using our Webservices API to include the additional field, credentialsonfile, with value set to “2”:


"credentialsonfile": "2"

 

Info
If the credentialsonfile field has been submitted in the request and it is supported by the acquirer processing the transaction, it is returned in the response JWT.

 


 

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.

 

Warning
This does not apply to Customer Initiated Transactions (CIT).

 

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:

Click here for further information on the different initiationreason values.

 

Info
You must ensure the initiationreason submitted in the request correctly represents the reason for the new payment. Visa may introduce new values to this list in the future. Please refer to Visa’s own documentation for further information.
PAYMENT
While this is only mandated by Visa, you can still submit these values in all your requests, and we will ignore them for other payment types.

 


 

Processing MIT using previously-stored credentials

In the AUTH request submitted using our Webservices API, include field initiationreason, setting the value to be one of those listed above.


"initiationreason": "S"

 

Warning
The MIT initiation reasons described within this document do not apply to scheduled / regular payments (e.g. subscriptions).

 

The MIT initiation reasons do not apply to transactions regarded as Customer Initiated Transactions (CIT).

 


 

Using MyST

Initial payment request including CoF

If using the Virtual terminal or processing an ST PayMe email, set Credentials on file to “1 – Credentials stored for re-use”, using the drop-down provided.

 

Later payment including CoF

When performing a re-auth, set Credentials on file to “2 – Payment using stored credentials”, using the drop-down provided.

 

Processing MIT

When performing a re-auth, set Initiation reason to one of the available values, as listed above.

 


 

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