Credential on File

On this page:

• Overview
• Store a Credential on File
• Use a Stored Credential
• Example
• Credential On File Data and Values

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

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.

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.

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