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 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 Direct 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.
Important: You can't initiate a transaction sequence with AccountType=C. Use E (ecommerce) or M (MOTO). If you wish to process through a Continuous Authority MID, this will need to be done as a subsequent transaction, or using a TOKEN, using COFUsage=SUBSEQUENT.

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.

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

 

 

Note: When you submit transaction types REPEAT or REPEATDEFERRED, then you cannot use the CoF fields. The REPEAT and REPEATDEFERRED transaction 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 REPEATDEFERRED transaction types.

CoF POST and Response Examples

Storing a CoF for later use as a MIT for unscheduled CoF transactions

Example POST

Note: The MITType is optional.

  • You may want to provide it upfront if you know what type of MIT you’ll always be using the stored CoF for.
  • If you will not use it as a MIT, or you will use multiple MIT types, then omit the MITType when first storing the CoF.
mount=32.00
ApplyAVSCV2=1
BillingAddress1=23
BillingAddress2=BillAddress+Line+2
BillingCity=London BillingCountry=GB BillingFirstnames=John BillingPhone=+447700900077
BillingPostcode=10
BillingSurname=Doe BrowserAcceptHeader=text/html,application/xhtml+xml,application/xml BrowserColorDepth=24
BrowserJavaEnabled=1
BrowserJavascriptEnabled=1
BrowserLanguage=en-GB BrowserScreenHeight=1080
BrowserScreenWidth=1920
BrowserTZ=%2B300
BrowserUserAgent=Mozilla
CV2=101
CardHolder=John+Doe
CardNumber=412xxxxxxx2xx71
CardType=Visa
ChallengeWindowSize=01
ClientIPAddress=10.10.10.10
Currency=GBP CustomerEMail=john.doe%40myopayo.com DeliveryAddress1=88
DeliveryAddress2=DelAddress+Line+2
DeliveryCity=London DeliveryCountry=GB DeliveryFirstnames=John DeliveryPhone=+447700900077
DeliveryPostcode=412+ODE DeliverySurname=Doe
Description=vendor-transaction-description
ExpiryDate=1220
ThreeDSNotificationURL=http%3A//vendor.com/notify
TransType=01
TxType=PAYMENT VPSProtocol=4.00
Vendor=vendor-Name
VendorTXCode=vendor-transaction-671294
Apply3DSecure=1    
COFUsage=FIRST    
InitiatedType=CIT    
MITType=UNSCHEDULED

Example Response when first storing a CoF

Note: You must store the SchemeTraceID value from the response when first storing a Credential on File. This value is required every time you use the Stored Credential. We advise you store the ACSTransID value as this can also be provided any time you use the stored credential.
VPSProtocol=4.00
Status=OK
StatusDetail=0000 : The Authorisation was Successful. 
VPSTxId={89B39FF0-B0B6-3041-70D4-97F6228D7204} 
SecurityKey=5NOBVDSDY0
TxAuthNo=4001830
AVSCV2=MATCH AddressResult=MATCHED 
PostCodeResult=MATCHED CV2Result=MATCHED
3DSecureStatus=OK 
CAVV=UWdveFY5aHdxcWprRkZXZUtGZ1o= 
DeclineCode=00
ExpiryDate=1220
BankAuthCode=999777
ACSTransID=f10fbf3d-6c1e-4b52-8d9c-ada37b0c09ce
DSTransID=8a4a47aa-6c38-465d-8250-c83890c58813
SchemeTraceID=V1234567890ABCDEFGXYZZPDENDOFTXS

Storing CoF as a MIT for an unscheduled CoF transaction

Example POST

Important: It is important that you use the SchemeTraceID value from the response when you first stored the Credential on File.

When InitiatedType=MIT, then you can omit the required 3D-Secure authentication fields including:

  • BrowserJavascriptEnabled. By not including this, a number of conditional 3D-Secure authentication fields are no longer necessary.
  • BrowserAcceptHeader
  • BrowserLanguage
  • BrowserUserAgent,
  • ThreeDSNotificationURL
  • ChallengeWindowSize
ApplyAVSCV2=1
BillingAddress1=23
BillingAddress2=BillAddress+Line+2
BillingCity=London
BillingCountry=GB
BillingFirstnames=John
BillingPhone=+447700900077
BillingPostcode=10
BillingSurname=Doe
CardHolder=John+Doe
CardNumber=412xxxxxxx2xx71
CardType=Visa
ClientIPAddress=10.10.10.10
Currency=GBP
CustomerEMail=john.doe@opayo.com
DeliveryAddress1=88
DeliveryAddress2=DelAddress+Line+2
DeliveryCity=London
DeliveryCountry=GB
DeliveryFirstnames=John
DeliveryPhone=+447700900077
DeliveryPostcode=412+ODE
DeliverySurname=Doe
Description=vendor-transaction-description
ExpiryDate=1220
TransType=01
TxType=PAYMENT
VPSProtocol=4.00
Vendor=vendor-dot-com
VendorTXCode=vendor-transaction-671294
COFUsage=SUBSEQUENT   
InitiatedType=MIT   
MITType=UNSCHEDULED   
SchemeTraceID=V1234567890ABCDEFGXYZZPDENDOFTXS

Example Response

Notes:

  • The returned SchemeTraceID value may be different to the one that you submitted in the request. We advise you to use the SchemeTraceID value returned when you first stored the CoF, and not the SchemeTraceID returned when using a Stored Credential.
  • It is possible that a soft decline response can be returned when submitting a MIT skips 3D-Secure authentication. The Handling Soft Declines section offers guidance.
PSProtocol=4.00
Status=OK
StatusDetail=0000 : The Authorisation was Successful.
VPSTxId={89B39FF0-B0B6-3041-70D4-97F6228D7204}
SecurityKey=5NOBVDSDY0
TxAuthNo=4001830
AVSCV2=ADDRESS MATCH ONLY
AddressResult=MATCHED
PostCodeResult=MATCHED
CV2Result=NOTPROVIDED
3DSecureStatus=NOTCHECKED
DeclineCode=00
ExpiryDate=1220
BankAuthCode=999777
SchemeTraceID=V1234567890ABCDEFGXYZZPDENDOJK21

Storing a CoF that will be later used as a CIT

Example POST

Amount=32.00
ApplyAVSCV2=1
BillingAddress1=23
BillingAddress2=BillAddress+Line+2
BillingCity=London
BillingCountry=GB
BillingFirstnames=John
BillingPhone=+447700900077
BillingPostcode=10
BillingSurname=Doe BrowserAcceptHeader=text/html,application/xhtml+xml,application/xml
BrowserColorDepth=24
BrowserJavaEnabled=1
BrowserJavascriptEnabled=1
BrowserLanguage=en-GB BrowserScreenHeight=1080
BrowserScreenWidth=1920
BrowserTZ=%2B300
BrowserUserAgent=Mozilla
CV2=101
CardHolder=John+Doe
CardNumber=412xxxxxxx2xx71
CardType=Visa
ChallengeWindowSize=01
ClientIPAddress=10.10.10.10
Currency=GBP
CustomerEMail=john.doe@opayo.com
DeliveryAddress1=88
DeliveryAddress2=DelAddress+Line+2
DeliveryCity=London
DeliveryCountry=GB
DeliveryFirstnames=John
DeliveryPhone=+447700900077
DeliveryPostcode=412+ODE
DeliverySurname=Doe
Description=vendor-transaction-description
ExpiryDate=1220
ThreeDSNotificationURL=http%3A//vendor.com/notify
TransType=01
TxType=PAYMENT VPSProtocol=4.00
Vendor=vendor-Name
VendorTXCode=vendor-transaction-671294
Apply3DSecure=1   
COFUsage=FIRST   
InitiatedType=CIT

Example Response

Note: You must store the SchemeTraceID value from the response when first storing a CoF. This value is required when you use the Stored Credential. We advise you to store the ACSTransID value to use each time you use the Stored Credential.
VPSProtocol=4.00
Status=OK
StatusDetail=0000 : The Authorisation was Successful.
VPSTxId={89B39FF0-B0B6-3041-70D4-97F6228D7204}
SecurityKey=5NOBVDSDY0
TxAuthNo=4001830
AVSCV2=MATCH AddressResult=MATCHED
PostCodeResult=MATCHED
CV2Result=MATCHED
3DSecureStatus=OK
CAVV=UWdveFY5aHdxcWprRkZXZUtGZ1o=
DeclineCode=00
ExpiryDate=1220
BankAuthCode=999777
ACSTransID=f10fbf3d-6c1e-4b52-8d9c-ada37b0c09ce
DSTransID=8a4a47aa-6c38-465d-8250-c83890c58813
SchemeTraceID=V1234567890ABCDEFGXYZZPDENDOFTXS

Storing a CoF as a CIT

Example POST

Notes:

  • Although 3D-Secure authentication is always required when the cardholder is in-session, you do not need to provide the Apply3DSecure=1. You provided this when first storing the Credential on File.
  • Opayo will leave it to the card issuer to determine if a frictionless or challenge authentication is required when using a stored credential.
  • We advise you to submit the ACSTransID value returned in the response when first storing the credential, as this can increase the chances of a frictionless authentication outcome.
mount=32.00
ApplyAVSCV2=1
BillingAddress1=23
BillingAddress2=BillAddress+Line+2
BillingCity=London BillingCountry=GB
BillingFirstnames=John
BillingPhone=+447700900077
BillingPostcode=10
BillingSurname=Doe
BrowserAcceptHeader=text/html,application/xhtml+xml,application/xml
BrowserColorDepth=24
BrowserJavaEnabled=1
BrowserJavascriptEnabled=1
BrowserLanguage=en-GB BrowserScreenHeight=1080
BrowserScreenWidth=1920
BrowserTZ=%2B300
BrowserUserAgent=Mozilla
CV2=101
CardHolder=John+Doe
CardNumber=412xxxxxxx2xx71
CardType=Visa
ChallengeWindowSize=01
ClientIPAddress=10.10.10.10
Currency=GBP
CustomerEMail=john.doe@opayo.com
DeliveryAddress1=88
DeliveryAddress2=DelAddress+Line+2
DeliveryCity=London
DeliveryCountry=GB
DeliveryFirstnames=John
DeliveryPhone=+447700900077
DeliveryPostcode=412+ODE
DeliverySurname=Doe
Description=vendor-transaction-description
ExpiryDate=1220
ThreeDSNotificationURL=http%3A//vendor.com/notify
TransType=01
TxType=PAYMENT VPSProtocol=4.00
Vendor=vendor-Name
VendorTXCode=vendor-transaction-671294
COFUsage=SUBSEQUENT   
InitiatedType=CIT   
SchemeTraceID=V1234567890ABCDEFGXYZZPDENDOFTXS

Example Response

VPSProtocol=4.00
Status=OK
StatusDetail=0000 : The Authorisation was Successful.
VPSTxId={89B39FF0-B0B6-3041-70D4-97F6228D7204}
SecurityKey=5NOBVDSDY0
TxAuthNo=4001830
AVSCV2=MATCH
AddressResult=MATCHED
PostCodeResult=MATCHED
CV2Result=MATCHED
3DSecureStatus=OK
CAVV=UWdveFY5aHdxcWprRkZXZUtGZ1o=
DeclineCode=00
ExpiryDate=1220
BankAuthCode=999777
ACSTransID=f10fbf3d-6c1e-4b52-8d9c-ada37b0c09ce
DSTransID=8a4a47aa-6c38-465d-8250-c83890c58813
SchemeTraceID=V1234567890ABCDEFGXYZZPDENDOJK21