Credentials on File

  Last updated: 

 

 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:

  • Processing an account check or authorisation request, where card details are to be re-used later.
  • Processing a re-authorisation.
  • Processing regular recurring payments.

  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.

  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:

  • 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

  In the interest of security, when 3-D Secure is enabled as part of your integration, all payments where credentials are flagged to be stored on file with credentialsonfile=1 are subject to a challenge request being performed, where the customer will be prompted to verify their identity.
Using MyST

If using the Virtual terminal or processing a Pay by Link email, set Credentials on file to “1 – Credentials stored for re-use”, using the drop-down provided.

CO4-EN.png

Payment Pages

For customers processing a transaction for the first time on your site, you will need to include credentialsonfile=1 in the POST to Payment Pages, as shown in the following example:

  It is imperative that the credentialsonfile field is also included in the string used to generate your request site security hash. Failure to do so will result in the customer being shown an “Invalid details” error message.

<form method="POST" action="<DOMAIN>/process/payments/choice">
<input type="hidden" name="sitereference" value="test_site12345">
<input type="hidden" name="currencyiso3a" value="USD">
<input type="hidden" name="mainamount" value="100.00">
<input type="hidden" name="version" value="2">
<input type="hidden" name="stprofile" value="default">
<input type="hidden" name="credentialsonfile" value="1">
<input type="submit" value="Pay">
</form>

Replace <DOMAIN> with a supported domain. Click here for a full list.

  If an error occurs (errorcode is not “0”), the credential cannot be considered a stored credential, and you must not use these card details in any subsequent payments.

API

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"

  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.

  If the parent response indicates an error occurred (errorcode is not “0”), the credential cannot be considered a stored credential, and you must not use these card details in any subsequent payments.

 

Payment from stored credentials

Using MyST

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

CO5-EN.png

Payment Pages

If you are processing a new payment using previously-stored credentials, you will need to include credentialsonfile=2 in the new request. This subsequent payment can only be processed using MyST (by selecting a transaction and clicking "Re-auth") or our Webservices API. Refer to the other tabs for further information.

API

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

"credentialsonfile": "2"

  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.

 

Processing Merchant Initiated Transactions

Transactions processed by the merchant are called Merchant Initiated Transactions (MIT).

You must always provide a reason for processing MIT. This is achieved by submitting the field initiationreason in the new payment request, 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.

Using MyST

In MyST, you must select the appropriate value from the drop-down on the Re-auth page (as shown below).

CO6-EN.png

Payment Pages

MIT are processed using MyST (by selecting a transaction and clicking "Re-auth") or our Webservices API. Refer to the other tabs for further information.

API

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 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).

  You must ensure the initiationreason submitted in the request correctly represents the reason for the new payment.

  The requirement to submit the initiationreason on MIT was mandated from 30th April 2018.

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

 

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:

Initiator Use case CoF value MIT value
Customer Payment where card details are to be stored for future payments 1 Don’t send
Customer Payment using stored card details 2 Don’t send
Merchant Previously-agreed regular subscription payments using stored card details 2 Don’t send
Merchant Re-authorisation due to a previous authorisation expiring, using stored card details 2 A
Merchant Unscheduled payment using stored card details 2 C
Merchant Delayed charge using stored card details 2 D
Merchant Re-submission of a previously-declined authorisation, using stored card details 2 S
Merchant Payment where the customer is charged for not showing up for a reservation, using stored card details 2 X
Was this article helpful?
0 out of 0 found this helpful