Protocol 3.00 > 4.00 Migration Guide

On this page:

Overview
Field validation
EMV 3DS
Apply3DSecure field
Credential on File
Response Crypt String
MyOpayo
What else?

Overview

For merchants using the Form integration method it is recommended that you upgrade to the latest version of the Opayo protocol (v4.00).

This will allow you to submit Credential on File information and use SCA Exemptions (though this is not recommended).

Important: If you are using customised templates, you may need to make changes. Contact support@opayo.io if you think you might be affected.

Field validation

To support EMV 3DS, the following changes have been made to the field validation:

BillingAddress1 maximum length is now 50 characters.
BillingAddress2 maximum length is now 50 characters.
DeliveryAddress1 maximum length is now 50 characters.
DeliveryAddress2 maximum length is now 50 characters.
You can no longer submit multiple CustomerEMail email addresses (colon seperated) as part of protocol 4.00. The maximum length acceptable is now 80 characters.

You can now sumbit a 3rd address line:

BillingAddress3, maximum length 50 characters.
DeliveryAddress3, maximum length 50 characters.

See the API Reference section for more information.

EMV3DS

Once you have upgraded to protocol 4.00, you will be able to submit optional fields to the 3D Secure process. This includes SCA Exemption and account level information, that will help us ensure your transactions are as frictionless as possible. Simply add these fields to your Crypt string.

**COF Data and Values**
Name	Description	Mandatory	Format	Max Length	Allowed Values
ThreeDSRequestor-AuthenticationInfoXML	Information about how you authenticated the cardholder before or during the transaction. For example, did your customer log into their online account on your website, using two-factor authentication, or did they log in as a guest?	No		Object
ThreeDSRequestorPrior-AuthenticationInfoXML	Information about how you authenticated the cardholder as part of a previous 3DS transaction. For example, were they authenticated via frictionless authentication or did a cardholder challenge occur?	No		Object
AcctInfoXML	Additional information about the cardholder’s account that has been provided by you. For example, how long has the cardholder had the account on your website?	No		Object
AcctID	The account ID, if applicable, of your customer’s account on your website.	No	Any	64
MerchantRiskIndicatorXML	Your assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted. For example, are you delivering goods to the cardholder’s billing address, is this a first-time order or reorder?	No		Object
TransType	Identifies the type of transaction being authenticated. 01 = Goods/Service Purchase 03 = Check Acceptance 10 = Account Funding 11 = Quasi-Cash Transaction 28 = Prepaid Activation and Load Values derived from the 8583 ISO Standard. Note: If you do not send TransType, the default value of 01 (Goods/Service Purchase) will be used.	No	Digits	2	01 03 10 11 28
ThreeDSExemptionIndicator	Required if Apply3DSecure=2 01 = Low Value Transaction (LVT) 02 = TRA exemption 03 = Trusted beneficiaries exemption 04 = Secure corporate payment 05 = Delegated authentication 06 – 99 Reserved for future use Learn more about SCA Exceptions.	Conditional	Digits 01 to 99	2	01 02 03 04 05

See our API reference section for more information.

Important: All of these fields are optional

Apply3DSecure field

The behaviour of this field has changed in Protocol 4.00. Specifically, if you are using Apply3DSecure=2 to suppress 3D secure checking, this will need to be accompanied by an SCA Exemption:

Name	Description	Mandatory	Format	Max Length	Allowed Values
Apply3DSecure	Set this flag to fine tune the 3D Secure checks and ruleset you have defined at a transaction level. This is useful when direct and trusted customer contact is established, and you want to override the default security check level. 0 = Default value. When 3D-Secure checks are possible and rules allow, perform the checks and apply the Authorisation rules. 1 = Force 3D-Secure challenge flow when possible and apply rules for Authorisation. 2 = Do not perform 3D-Secure checks for this transaction and always Authorise. Only use when you can provide a valid SCA Exemption reason ThreeDSExemptionIndicator. 3 = Force 3D-Secure checks for this transaction when possible and ALWAYS send for Authorisation, irrespective of rulebase and if the cardholder has failed Authentication. Following the SCA mandate, we recommend you do not use this flag. If the cardholder fails authentication, and the request is sent for authorisation, expect the payment to be declined by the card issuer. This field is ignored for PayPal transactions.	No	Digits	Flag	0 1 2 3

Name

Description

Mandatory

Format

Max Length

Allowed Values

Apply3DSecure

Set this flag to fine tune the 3D Secure checks and ruleset you have defined at a transaction level. This is useful when direct and trusted customer contact is established, and you want to override the default security check level.

0 = Default value. When 3D-Secure checks are possible and rules allow, perform the checks and apply the Authorisation rules.
1 = Force 3D-Secure challenge flow when possible and apply rules for Authorisation.
2 = Do not perform 3D-Secure checks for this transaction and always Authorise. Only use when you can provide a valid SCA Exemption reason ThreeDSExemptionIndicator.
3 = Force 3D-Secure checks for this transaction when possible and ALWAYS send for Authorisation, irrespective of rulebase and if the cardholder has failed Authentication.
Following the SCA mandate, we recommend you do not use this flag. If the cardholder fails authentication, and the request is sent for authorisation, expect the payment to be declined by the card issuer.
This field is ignored for PayPal transactions.

Digits

Flag

Credential On File

If you wish to store a card number for possible future use, you will need to upgrade to protocol 4.00 - if you do not, unfortunately you will find increasing numbers of transactions decline. This is due to the payment card industry tightening standards, and introducing new processing procedures.

Once you have upgraded to protocol 4.00, you will need to submit extra fields to Opayo, in order to let us know that you will be processing transactions from a stored card including any REPEAT transactions that you will take via MyOpayo or the Shared protocol.

The fields you will need to add to the Crypt string:

**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.	Conditional. (Required if you will be REPEATing transactions)	Uppercase letters	10	Will always be FIRST
InitiatedType	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	Will always be CIT
MITType	This field is optional. If you know what kind of transactions you will be doing in the future, you can provide this information. 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.	Optional	Uppercase 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

See our API reference and/or Credential on File section for more information.

Response Crypt String

Please be aware that the following fields will addtionally be returned as part of the encrypted string. Make sure that these won't break your existing integration.

ACSTransID

The Access Control Server (ACS) transaction ID is a unique ID provided by the card issuer for 3DSv2 authentications. It is returned in future transaction requests that perform 3D-Secure authentication. It encourages a frictionless authentication, especially if a challenge authentication has occurred previously.

This value is returned to Opayo when you submit your Direct payment request using the threeDSReqPriorRef element found within the ThreeDSRequestorPriorAuthenticationInfoXML object.

DSTransID

The Directory Server (DS) transaction ID is a unique ID provided by the card scheme for 3DSv2 authentications.

SchemeTraceID

This is the unique reference number associated with an authorisation request.

Note: The SchemeTraceID will always be returned for a successful authorisation (where Status=OK).

ITU-T T.50 value codes.

ASCII range in hexadecimal from

20 to 7E (from

space to tilde ~)

What Else?

When Opayo introduce new features later in the year, these will only be made available to merchants processing on protocol 4.00. More information to follow.