Credential on File

On this page:


A Credential on File transaction is when you store the cardholder’s card data to make a payment later.

The payment can be taken either:

  • With the cardholder in-session known as Consumer Initiated Transaction (CIT), when the cardholder submits a payment when visiting your website or an App, or
  • When the cardholder is off-session known as Merchant Initiated Transactions (MIT), where you submit the payment request on behalf of the cardholder. An example is a recurring subscription payment.

Declaring that you are storing a Credential on File means that you can continue to repeat transactions via MyOpayo and use the REPEAT and REPEATDEFERRED transaction types.

Since the PSD2 mandated changes for 3D-Secure authentication, the way Credential on File transactions are stored is changed. To store cardholder data to file:

  1. A challenge authentication and an authorisation must occur.
  2. Both authentication and authorisation responses must be successful.

If either are unsuccessful, then you:

  • Cannot automatically store the Credential on File.
  • Must advise the cardholder that you intend to store their Credential on File.
  • Must advise the cardholder in your Terms and Conditions (T&Cs) how stored credential data is used.

Store a Credential on File

Complete the following steps to store a Credential on File. You can only store the Credential on File when the result of 3D-Secure authentication and authorisation are successful.

Important: Please consult with your acquirer and your legal representative to ensure your T&Cs meet your business needs and comply with laws and regulations within your country.

Step 1. Agree Terms and Conditions (T&Cs)

  1. Provide your T&Cs to the cardholder advising that you’ll store the Credential on File and including:
    1. What you’ll be using the stored credential for.
    2. How the contractual agreement is setup and how it may be cancelled.
    3. How and by whom the stored credential can be removed.
  2. Where applicable, also include:
    1. The expiration date of the agreement
    2. Fees that can be incurred
    3. The length of any trial period, introductory offer or promotional period.
  3. You must then:
    1. Provide a written copy of the T&Cs to the cardholder.
    2. Obtain the cardholder’s explicit agreement to the T&Cs and return a record of their consent.

Step 2. Submit a payment request

  1. Set Apply3DSecure=1 to advise 3D-Secure authentication is performed (challenge authentication)
  2. Request the storing of a Credential on File. Submit the following Credential on File fields:
    1. COFUsage=FIRST
    2. InitiatedType=CIT.
  3. An optional field, MITType=nn, can be submitted, where nn is a relevant MITType value from the Credential on File table.
    1. If the MITType=RECURRING, then also provide the RecurringExpiry and RecurringFrequency fields and values.
    2. If the MITType=INSTALMENT, then also provide the RecurringExpiry, RecurringFrequency, and PurchaseInstalData fields and values.

Step 3. Confirm the Response

When 3D-Secure authentication is successful, then we will perform an authorisation request and respond with the relevant fields and values.

When both 3D-Secure authentication and authorisation are completed, we will return a SchemeTraceID value in the response. This is a unique scheme reference that you must store for re-use when you use the stored credential for future transactions. The value is obtained during authorisation.

You will also receive the ACSTransID and the DSTransID in the response. The values are obtained during 3D-Secure authentication.

Use the ACSTransID when using a Stored Credential to advise the card schemes that a challenge authentication took place previously when the credential was first stored. You can submit the ACSTransID value in the ThreeDSRequestorPriorAuthenticationInfoXML object in your Opayo Direct payment request. .

Use a Stored Credential

Using Form, you can use a stored credential via MyOpayo (REPEAT, REPEATDEFERRED) or using the Shared protocol.