- Overview
- Field validation
- MOTO Processing
- EMV 3DS
- Apply3DSecure field
- Credential on File
- SchemeTraceID
- New Response fields
- What else?
Overview
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 .
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.
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.
MOTO Processing
If you have integrated via Direct to process MOTO payments only, you will not need to integrate the EMV 3DS fields described below. You should update the VPSProtocol field to 4.00, consider whether the Credential on File fields are applicable and check your integration can handle any of the additional response data.
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.
Required when BrowserJavascriptEnabled = 1 |
Conditional |
Digits |
|
|
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.
Required if BrowserJavascriptEnabled = 1 |
Conditional |
Digits |
1 to 2 |
|
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:
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.
|
Yes |
Digits |
2 |
|
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? |
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? |
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? |
No |
|
Object |
|
TransType |
The type of transaction being authenticated.
Values derived from the 8583 ISO Standard. Note: When blank, the default value is 01 (Goods/ Service Purchase). |
No |
Digits |
2 |
|
ThreeDSExemptionIndicator |
Required when Apply3DSecure=2:
|
Conditional |
Digits 01 to 99 |
2 |
|
For information handling 3DSv2 authentication flow see:
Forward to ACSURL
Post from Terminal URL
You may also find the 3D Secure Transactions 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.
|
No |
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 tokens and REPEAT transactions that you will take via MyOpayo or the Shared protocol.
The fields you will need to add to the post on transaction registration:
Name |
Description |
Mandatory |
Format |
Max Length |
Allowed Values |
---|---|---|---|---|---|
COFUsage |
|
Conditional. (Required if you will be REPEATing transactions) |
Uppercase letters |
10 |
Will always be FIRST |
InitiatedType |
|
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.
|
Optional
|
Uppercase letters |
15 |
|
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 |
|
If you wish to use a token via Direct, you will need to submit the following fields with the transaction registration:
Name |
Description |
Mandatory |
Format |
Max Length |
Allowed Values |
---|---|---|---|---|---|
COFUsage |
|
Required if you are using a token.
|
Uppercase letters |
10 |
Will always be SUBSEQUENT |
InitiatedType |
|
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.
|
Optional
|
Uppercase letters |
15 |
|
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. |
|
|
36 |
|
DSTransID |
The Directory Server (DS) transaction ID is a unique ID provided by the card scheme for 3DSv2 authentications. |
|
|
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 |
|
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.