Protocol 2.23 > 4.00 Migration Guide

Overview

Protocol 2.23 was deprecated in 2012. Industry changes (notable Credential on File and SCA) means that if you are using the Direct integration method, you must upgrade to protocol 4.00.

This will allow you to process transactions in a manner compliant with PSD2, as well as submit Credential on File information and use SCA Exemptions (though this is not recommended).

If this is going to require significant rework, it might be worth considering migrating to our Pi integration, which has a PCI SAQ A / EP reqiuirement, as opposed to SAQ D.

Important: If you are using the standalone token endpoint, this will be come non-SCA compliant by March 2022 - you will need to register tokens as part of a transaction going forward. Contact support@opayo.io for advice and assistance.

 

New Fields

The following optional fields were added to protcol 3.00 and support for these has been carried through to protcol 4.00:

 

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

BasketXML

A more flexible version of the current basket field which can be used instead of the basket field.

If this field is supplied then the Basket field should not be supplied.

No

 

20000

 

CustomerXML

This can be used to supply information on the customer for purposes such as fraud screening.

No

 

2000

 

VendorData

Use this field to pass any data you wish to be displayed against the transaction in MySagePay.

No

Letters, digits, and spaces

  

200

 

ReferrerID

This can be used to send the unique reference for the Partner that referred the Vendor to Opayo.

No

Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed

             

40

 

Website

Reference to the website this transaction came from. This field is useful if transactions can originate from more than one website.

Supplying this information will enable reporting to be performed by website.

No

Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed

             

100

 

FIRecipientAcctNumber

This should either be the first 6 and the last four characters of the primary recipient PAN (no spaces).

Where the primary recipient account is not a card this will contain up to 10 characters of the account number (alphanumeric), unless the account number is less than 10 characters long in which case the account number will be present in its entirety.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Letters and digits

 

10

 

FIRecipientSurname

This is the surname of the primary recipient.

No special characters such as apostrophes or hyphens are permitted.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Letters and spaces

 

20

 

FIRecipientPostcode

This is the postcode of the primary recipient.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Letters, digits, and spaces

  

?

 

FIRecipientDoB

This is the date of birth of the primary recipient in the format YYYYMMDD.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Digits

 

 

 

Additionally, protcol 3.00 improved token handling. We now offer the ability to save a token on transaction registration, rather than using the standalone token endpoint:

 

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

CreateToken

Set this flag to indicate that you want a token generated and stored in our database and returned to you for future use.

  • 0 = Default value. This will not create a token from the payment.

  • 1 =This will create a token from the payment if successful and return a Token.

Important: In order to create a token appropriate Credential on file fields must be supplied.

No

BOOLEAN

Flag

  • 0

  • 1

StoreToken

Set this flag to indicate that you want to store the token for future use.

  • 0 = Do not store Token (default)

  • 1 = Store Token after three failed attempts or after a successful authorisation.

Note. To store a Token more than once, a value of 1 must be passed each time the Token is used.

No

BOOLEAN

Flag

  • 0 (default)

  • 1

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.

EMV 3DS

You will need to provide the following mandatory fields in order to initiate a EMV 3DS authentication (3DS v2).

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

BrowserJavaEnabled

Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property.

  • 0 = False

  • 1 = True

Required when BrowserJavascriptEnabled = 1

Conditional

Digits

 

  • 0

  • 1

BrowserColorDepth

Representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from cardholder browser using the screen.colorDepth property.

  • 1 = 1 bit

  • 4 = 4 bits

  • 8 = 8 bits

  • 15 = 15 bits

  • 16 = 16 bits

  • 24 = 24 bits

  • 32 = 32 bits

  • 48 = 48 bits

Required if BrowserJavascriptEnabled = 1

Conditional

Digits

1 to 2

  • 1

  • 4

  • 8

  • 15

  • 16

  • 24

  • 32

  • 48

BrowserScreenHeight

Total height of the cardholder’s screen in pixels.

Value is returned from the screen.height property.

 

Required if BrowserJavascriptEnabled= 1

Conditional

Digits

1-6

 

BrowserScreenWidth

Total width of the cardholder’s screen in pixels. Value

is returned from the screen.width property.

 

Required if BrowserJavascriptEnabled= 1

Conditional

Digits

1-6

 

BrowserTZ

Time-zone offset in minutes between UTC and the Cardholder browser local time. The offset is positive if the local time zone is behind UTC and negative if it is ahead indicated with a hyphen. 

Example time zone offset values in minutes:

  • If UTC is minus 5 hours (i.e. minus 300 minutes) value is +300

  • If UTC is +5 hours (i.e. +300 minutes) value is -300

Required if BrowserJavascriptEnabled= 1

Conditional

Digits, hyphens, and plus
  

1-6

 

BrowserAcceptHeader

The content of the HTTP accept headers as sent to you from the Cardholder’s browser including the exact content of the Accept field. An example value is: text/html,application/xhtml+xml,application/xml;q=0.9,

*/*;q=0.8

Yes

Any

2048

 

BrowserLanguage

Representing the browser language as defined in IETF BCP47. Returned from navigator.language property.

Yes

As defined in IETF BCP47

8

 

BrowserUserAgent

Exact content of the HTTP user-agent header.

Yes

Any

2048

 

ThreeDSNotificationURL

Fully qualified URL of the system that receives the CRes (Challenge Response) message or Error Message and where your customer will be returned once they have completed their challenge.

The CRes message is posted by the ACS (Access Control Server) through the cardholder browser at the end of the challenge AND once the ACS receives an RRes (Result Response) message from Opayo .

Yes

RFC1738

255

 

ChallengeWindowSize

Dimensions of the challenge window that has been displayed to the cardholder.

To provide the best possible user experience, the ACS replies with challenge content formatted to render in this window. Preconfigured sizes are width by height in pixels of the window displayed in the Cardholder browser window.

  • 01 = 250 by 400

  • 02 = 390 by 400

  • 03 = 500 by 600

  • 04 = 600 by 400

  • 05 = Full screen

Yes

Digits

2

  • 01

  • 02

  • 03

  • 04

  • 05

 

You will also 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 transaction registration post.

 

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

ThreeDSRequestor

AuthenticationInfoXML

Describing 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?

Refer to the ThreeDSRequestorAuthenticationInfoXML section.

No

 

Object

 

ThreeDSRequestorPrior

AuthenticationInfoXML

Describing 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?

Refer to the ThreeDSRequestorPriorAuthenticationInfoXML section.

No

 

Object

 

AcctInfoXML

Additional information about the Cardholder’s account. For example, how long has the cardholder had the account on your website?

Refer to the AcctInfoXML section.

No

 

Object

 

AcctID

The account ID of your customer's account on your website when applicable.

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 and is this a first-time order or reorder?

Refer to the MerchantRiskIndicatorXML section.

No

 

Object

 

TransType

The type of transaction being authenticated.

  • 01 = Default value. 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: When blank, the default value is 01 (Goods/ Service Purchase).

No

Digits

  • 01

  • 03

  • 10

  • 11

  • 28

ThreeDSExemptionIndicator

Required when Apply3DSecure=2:

  • 01 = Low Value Transaction (LVT)

  • 02 = TRA exemption

  • 03 = Trusted beneficiaries exemption

  • 04 = Secure corporate payment

  • 05 = Delegated authentication

  • 06 to 99 = Reserved for future use

Refer to the SCA Exemptions section.

Conditional

Digits 01 to 99

  • 01

  • 02

  • 03

  • 04

  • 05

 

For information handling a 3DSv2 authentication flow see:

Forward to ACSURL
Post from Terminal URL

You may also find this page useful.

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

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 tokens and REPEAT transactions that you will take via My Sage Pay or the Shared protocol.

The fields you will need to add to the post on transaction registration:

COF Registration Fields

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

 

 

Important: If you are processing via a MOTO MID, your InitiatedType will always be a CIT
Important: If you wish to process via a CA MID, you will need to do using a stored credential, and do so as a subsequent transaction (COFUsage=SUBSEQUENT)

 

If you wish to use a token via Direct, you will need to submit the following fields with the transaction registration:
 

COF Usage Fields

Name

Description

Mandatory

Format

Max Length

Allowed Values

COFUsage

  • SUBSEQUENT = You are using a stored Credential on File. This is the second (or greater) transaction using the stored credential. For example, if you have submitted a token with your transaction registration post.

Required if you are using a token.

 

Uppercase letters

10

Will always be SUBSEQUENT 

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

Note. Submitting a recurring transaction after the declared Recurring Expiry Date may result in the transaction request being declined by the card issuer.

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.

Note. When the declared number of instalments have passed, any extra instalments taken may result in the transaction request being declined by the card issuer.

Conditional

Digits

3

 

 

See our API Reference or Credential on File section for more information.

SchemeTraceID

If you store consumer card numbers, but wish to use these to process transactions as MITs, submitting the PAN with your transaction request, you will need to capture the SchemeTraceID value on the initial transaction (COFUsage=FIRST), and supply it on the subsequent transaction (COFUsage=SUBSEQUENT).

Name

Description

Mandatory

Format

Max Length

Allowed Values

SchemeTraceID

This is the unique reference number associated with an authorisation request. It is required when you use a

stored Credential on File, and links subsequent payments with the first payment.

 

Note: The SchemeTraceID will always be returned for a successful authorisation (where Status=OK). However, the value returned when you first store a Credential on File, is the one that you should submit in your Direct payment request when using a stored credential.

No

ITU-T T.50 value codes.

ASCII range in hexadecimal from

20 to 7E (from

space to tilde)

56 

 

New Response fields

Please be aware that the following fields will addtionally be returned as part of the response post. 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.

No

 

36 

 

DSTransID

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

No

 

36

 

SchemeTraceID

This is the unique reference number associated with an authorisation request. It is required when you use astored Credential on File, and links subsequent payments with the first payment.

 

Note: The SchemeTraceID will always be returned for a successful authorisation (where Status=OK). However, the value returned when you first store a Credential on File, is the one that you should submit in your Direct payment request when using a stored credential.

No

ITU-T T.50 value codes.

ASCII range in hexadecimal from

20 to 7E (from

space to tilde ~)

56

 

BankAuthCode

The authorisation code returned from the bank. e.g. T99777

No