Credential on File

On this page:

Overview

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 MySagePay 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.
Important: If your transaction has an account type of M your InitiatedType will always need to be CIT.

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

Submit a Direct payment request and include the relevant Credential on File fields and values from the Credential on File table.

Cardholder is in-session

When the cardholder is in-session use the following Credential on File fields:

  • COFUsage=SUBSEQUENT
  • InitiatedType=CIT and the SchemeTraceID that had been returned to you when you first stored the Credential on File.

We recommend that you provide the ACSTransID value within the ThreeDSRequestorPriorAuthenticationInfoXML object to improve the chance of a frictionless authentication. You should have received the ACSTransID value when you first stored the Credential on File.

As the cardholder is in session, 3D-Secure authentication is required although the Apply3DSecure field and value are not required. Opayo Direct allows the card issuer to determine if a challenge or frictionless authentication is necessary.

Cardholder is off-session

When the cardholder is off-session, then use the following Credential on File fields:

  • COFUsage=SUBSEQUENT
  • InitiatedType=MIT
  • MITType=nn (where nn is a relevant MITType value from the Credential on File table)
  • The SchemeTraceID that had been returned to you when you first stored the Credential on File.

If the MITType value is:

  • RECURRING, then also provide the RecurringExpiry and RecurringFrequency fields and values.
  • INSTALMENT, then also provide the RecurringExpiry, RecurringFrequency and PurchaseInstalData fields and values.

Note: If the MITType value is RECURRING or INSTALMENT, we advise you provide the ACSTransID value received when you first stored the Credential on File, within the ThreeDSRequestorPriorAuthenticationInfoXML object.

Recurring and instalment transactions are always sent for authentication, even though the cardholder is off-session. Providing the ACSTransID from the first transaction will aid in a successful 3D-Secure authentication result.

Use a Token

When using a Stored Credential using a Token, you do not need to send the SchemeTraceID value. We will retrieve this and send it in the authorisation request for you.

Stored Credentials from Pre-PSD2

If you stored a Credential to File before the PSD2 mandated changes, then you are not expected to receive a SchemeTraceID value after the first transaction went through SCA.  

You can use the Stored Credentials as MITs or CITs and you must advise us that the Stored Credential was stored before the PSD2 mandate using the SchemeTraceID value of SP999999999.  

When the transaction is authorised, you will receive a new SchemeTraceID value to use for all subsequent related transactions.

Credential on File Data and Values

COF Data and Values

Name

Description

Mandatory

Format

Max Length

Allowed Values

COFUsage

  • FIRST = You are storing Credential to File. This is the first of a series of transactions using the same stored credential. 
    Note: The cardholder must be in-session as they are required to perform a challenge authentication before you can safely store a Credential on File.

  • SUBSEQUENT = You are using a stored Credential on File. You must provide the SchemeTraceID that was returned to you when you first stored the Credential on File.

Conditional.

(Required if creating or using tokens or for REPEAT transactions or if you are storing / reusing credentials).

Uppercase letters

10

  • FIRST

  • SUBSEQUENT

InitiatedType

  • MIT = The cardholder is off-session. 3D-Secure authentication will not be performed for these transactions.

  • CIT = The cardholder is in-session. 3D-Secure authentication will be performed for these transactions.

Conditional.

(Required if COFUsage

value is present).

Uppercase letters

3

  • MIT

  • CIT

MITType

  • INSTALMENT = A single purchase of goods or services that is paid for over time as agreed by the cardholder and you. You must provide the RecurringExpiry, RecurringFrequency and PurchaseInstalData fields and values.

  • RECURRING = Multiple purchases for different goods and, or services where the transaction is processed at fixed, regular intervals not exceeding one year between transactions. It represents an agreement between you and the cardholder to purchase goods or services provided over a period of time.

  • UNSCHEDULED = A transaction for a fixed or variable amount that does not occur on a fixed, scheduled, or regularly occurring transaction date.

  • INCREMENTAL = Typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract. For example, room service is added to the cardholders invoice. They must be preceded by an estimated and, or initial authorisation. An incremental authorisation is in addition to the original estimated authorisation. 
    Note. These are only available for certain MCC codes.

  • DELAYEDCHARGE = Typically used in hotel, cruise lines, and vehicle rental environments to perform a supplemental account charge after original services are rendered. For example, a parking fine.

  • NOSHOW = Used to charge for services for which the cardholder entered into an agreement to purchase and failed to meet the terms of the agreement. For example, meeting the terms of a ‘no show’ after booking a hotel room.

  • REAUTHORISATION = When a further purchase is made after the original purchase. For example, extended stays and, or rentals. It can also be used in split shipment scenarios.

  • RESUBMISSION = When an original purchase occurred, the goods or services are already provided, and you were unable to get a successful authorisation at the time.

Conditional.

(Required if InitiatedType = MIT, 

optional if InitiatedType = CIT) 

 

Uppercase letters

15

  • INSTALMENT

  • RECURRING

  • UNSCHEDULED

  • INCREMENTAL

  • DELAYEDCHARGE

  • NOSHOW

  • REAUTHORISATION

  • RESUBMISSION

 

SchemeTraceID

Required if COFUsage=SUBSEQUENT. Not required if using Tokens

Conditional

Letters and digits
 

56

208000FDD32G3

RecurringExpiry

Required if MITType=RECURRING or MITType=INSTALMENT.

Conditional

Digits and hyphens
 

10

YYYY-MM-DD

RecurringFrequency

Required if MITType=RECURRING or MITType=INSTALMENT.

The value is the number of days. For example, an annual frequency would be 365.

Conditional

Digits

4

 

PurchaseInstalData

Required if MITType=INSTALMENT.

Conditional

Digits

3