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 to Force to ensure 3D-Secure authentication is performed (challenge authentication)
  2. Request the storing of a Credential on File. Submit the following Credential on File fields as part of the credentialType object:
    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 entryMethod of MailOrder or TelephoneOrder your initiatedType will always need to be CIT.

Example CoF object

The following is an example credential on file object. Add this to your transaction post:

"credentialType":
{
 "cofUsage":"First", 
"initiatedType":"CIT", 
"mitType":"Unscheduled" 
}

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.

You will 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 threeDSReqPriorRef field in the threeDSRequestorPriorAuthenticationInfo object in the strongCustomerAuthentication object within payment request. .

Use a Stored Credential

Submit a 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 

We recommend that you provide the ACSTransID as threeDSReqPriorRef within the threeDSRequestorPriorAuthenticationInfo 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. Pi 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)

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 ThreeDSRequestorPriorAuthenticationInfo object as a value within the threeDSReqPriorRef .

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.

Example

Important: This step is necessary only for eCommerce transactions using entryMethod:Ecommerce. It is not necessary for Mail Order and, or Telephone Order (MOTO) transactions.

The transaction example below demonstrates when the customer is off-session (MIT) and 3D Secure authentication is not necessary:

  • The example also applies to when the customer is in-session (CIT) and 3D Secure authentication is necessary.
  • Challenge authentication is not necessary. The card issuer can respond with a challenge authentication request or provide a frictionless authentication result.

For a CIT scenario, replace initiatedType:MIT with initiatedType:CIT and add the following fields:

  • strongCustomerAuthentication object (request 3D Secure authentication).
  • apply3DSecure:UseMSPSetting.

Example eCommerce transaction

The following example demonstrates using a token for a subsequent transaction, with the customer out of session (therefore a MIT):

{
    "transactionType": "Payment",
    "paymentMethod": {
        "card": {
            "merchantSessionKey": "<merchant-session-key>",
            "cardIdentifier": "<card-identifier>",
            "reusable": true
        }
    },
    "vendorTxCode": "demotransaction-<unique-suffix>",
    "amount": 41000,
    "currency": "GBP",
    "description": "Demo transaction",
    "customerFirstName": "John",
    "customerLastName": "Doe",
    "billingAddress": {
        "address1": "407 St. John Street",
        "city": "London",
        "postalCode": "EC1V 4AB",
        "country": "GB"
    },
    "entryMethod": "Ecommerce",
    "customerPhone": "+447447001100",
    "customerMobilePhone": "+447447001122",
    "customerWorkPhone": "+447447001133",
    "credentialType": {
        "cofUsage": "Subsequent",
        "initiatedType": "MIT",
        "mitType": "Unscheduled"
    }
}

Example with Stored Credential

The following example is of a response when using a stored credential:

{
    "transactionId": "DB79BA2D-05DA-5B85-D188-1293D16BBAC7",
    "transactionType": "Payment",
    "status": "Ok",
    "statusCode": 0,
    "statusDetail": "The Authorisation was Successful.",
    "retrievalReference": 9493946,
    "bankResponseCode": 0,
    "bankAuthorisationCode": 999777,
    "avsCvsCheck": {
        "status": "AllMatched",
        "address": "Matched",
        "postalCode": "Matched",
        "securityCode": "Matched"
    },
    "paymentMethod": {
        "card": {
            "merchantSessionKey": "90BDF208-3C19-40AC-858B-3F4054DCD1C0",
            "cardIdentifier": "cardTokenUUID",
            "reusable": true
        }
    },
    "amount": 4100,
    "currency": "GBP"
}

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.

Conditional.

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

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

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) 

 

Letters

15

  • Instalment 

  • Recurring

  • Unscheduled

  • Incremental

  • DelayedCharge 

  • NoShow

  • Reauthorisation

  • Resubmission 

 

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

 

 

Note: When you submit transaction types Repeat or RepeatDeferred, then you cannot use the CoF fields. The Repeat and RepeatDeferredtransaction types are MITs by default and have the following default values associated with them when submitted for authorisation:

  • COFUsage=SUBSEQUENT
  • InitiatedType=MIT
  • MITType=UNSCHEDULED

A planned enhancement will enable CoF fields to be submitted for Repeat and Repeat Deferred transaction types.