When your customer submits your payment form, a script on your web server constructs a Transaction Registration POST. This is sent to the Opayo Direct payment URL using HTTPS.
Name |
Description |
Mandatory |
Valid Characters |
Max Length |
Allowed Values |
---|---|---|---|---|---|
VPSProtocol |
The version of the protocol you are integrating with. The Default value is 4.00, used when an invalid value is given. |
Yes |
Digits and periods |
4 |
4.00 |
TxType |
Transaction Type. This must be in UPPERCASE. |
Yes |
Uppercase letters |
15 |
|
Vendor |
Used to authenticate your site. This must contain the Opayo Vendor Name given to you on account creation. |
Yes |
Letters and digits |
15 |
|
VendorTxCode |
Your unique transaction reference. You must use a new and unique VendorTxCode for each transaction. |
Yes |
Letters, digits, hyphens, periods, underscores, and curly brackets |
40 |
|
Amount |
The transaction amount. Validation:
|
Yes |
Digits, periods
|
|
0.00 to 100000.00 |
Currency |
The transaction currency. This must be supported by one of your Opayo merchant accounts or the transaction will be rejected. |
Yes |
ISO4217
|
3 |
|
Description |
Free text description of goods or services being purchased. |
Yes |
HTML
|
100 |
|
CardHolder |
This should be the name displayed on the card. Due to card scheme requirements, accented characters are not supported.
|
Conditional |
Letters |
45 |
|
CardNumber |
The full card number is required. Not required if CardType=PAYPAL |
Conditional |
Digits |
20 |
|
ExpiryDate |
The expiry date of the card in the format of MMYY Not required if CardType=PAYPAL |
Conditional |
Digits![]() |
4 | MMYY |
CV2 |
The 3 digits on the signature strip of the card, or the extra 4 digits on the front for American Express Cards. If AVS/CV2 is ON for your account this field becomes compulsory. Not required if CardType=PAYPAL |
Conditional |
Digits![]() |
4 | |
|
|
Uppercase letters |
|
|
|
Token |
The Token provided during the token registration phase. |
No |
Letters, digits, hyphens, and curly brackets
|
38 |
|
BillingSurname |
Important: For a successful 3DSv2 authentication, all up to date billing information including BillingPhone should be provided by your customer. Incorrect billing information may result in authentication failing or your customer being challenged during the authentication process by their card issuer rather than the preferred frictionless authentication occurring.
|
Yes |
Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, and spaces
|
20 |
|
BillingFirstnames |
|
Yes |
Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, and spaces
|
20 |
|
BillingAddress1 |
|
Yes |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed
|
50 |
|
BillingAddress2 |
|
No |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed
|
50 |
|
BillingAddress3 |
|
No |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed
|
50 | |
BillingCity |
|
Yes |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed
|
40 |
|
BillingPostCode |
Mandatory for countries that support Post Codes.
|
Conditional |
Letters, digits, hyphens, and spaces
|
10 |
|
BillingCountry |
|
Yes |
ISO3166 |
2 |
Examples:
|
BillingState |
Mandatory when the BillingCountry is set to US. |
Conditional |
Valid 2-letter US States US |
2 |
Examples:
|
BillingPhone |
The BillingPhone should be formatted with:
Example: For a UK phone number of 01234 567891, you will submit the following: +441234567891 |
No |
Letters, digits, hyphens, spaces, parentheses, and plus |
19 |
|
DeliverySurname |
Important: For a successful 3DSv2 authentication, all up to date delivery information including DeliveryPhone should be provided by your customer. Incorrect billing information may result in authentication failing or your customer being challenged during the authentication process by their card issuer rather than the preferred frictionless authentication occurring.
|
Yes |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, and spaces |
20 |
|
DeliveryFirstnames |
|
Yes |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, and spaces
|
20 |
|
DeliveryAddress1 |
|
Yes |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed |
50 |
|
DeliveryAddress2 |
|
No |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed |
50 |
|
DeliveryAddress3 |
|
No |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed |
50 |
|
DeliveryCity |
|
Yes |
Letters including accents, digits, ampersand, commas, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, plus, and carriage returns or line feed
|
40 |
|
DeliveryPostCode |
Mandatory for countries that support Post Codes. |
Conditional |
Letters, digits, hyphens, and spaces
|
10 |
|
DeliveryCountry |
|
Yes |
ISO3166 |
2 |
|
DeliveryState |
Mandatory when DeliveryCountry is set to US.
|
Conditional |
Valid 2-letter US States US |
2 |
Examples:
|
DeliveryPhone |
|
No |
Letters, digits, hyphens, spaces, parentheses, and plus |
20 |
|
PayPalCallbackURL |
Fully qualified domain name of the URL to which customers are redirected upon completion of a PayPal transaction. Only required if CardType=PAYPAL |
Conditional |
RFC1738 |
255 |
|
CustomerEMail |
Your customers email address. Important: Required for 3DSv2 toward a successful authentication unless market or regional mandate restricts sending this information.
|
Conditional |
RFC532N |
80 |
Examples:
|
Basket |
This Basket content is displayed in MyOpayo. Important. When this field contains a value, you must leave the BasketXML field blank. |
No |
|
7500 |
|
GiftAidPayment |
Set this flag to 1 to present the Gift Aid acceptance box to your customer on our transaction payment page when your vendor account is Gift Aid enabled.
|
No |
BOOLEAN |
Flag |
|
ApplyAVSCV2 |
Set this flag to fine tune the AVS/CV2 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.
Note. This field is ignored for PayPal and European Payment method transactions. |
No |
Digits |
Flag |
|
ClientIPAddress |
The IPv4 or IPv6 IP address of your customer connecting to your server making the payment returned by the HTTP headers. This must be the full IP address which you can obtain from your server scripts. Required for 3DSv2 authentication. Note: For 3DSv2 authentication to be successful. It is strongly recommended that this is provided correctly and is your customers IP address. |
Conditional |
Digits and periods |
39 |
|
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.
Notes:
|
No |
Digits |
Flag |
|
AccountType |
Set this flag to tell the Opayo gateway which merchant account to use. When omitted, the system will use E, then M, and then C by default.
Note. This field is ignored for PayPal transactions. |
No | Uppercase letters![]() |
1 |
|
BillingAgreement |
Set this flag to 1 when you want to register this transaction as the first in a series of regular payments.
Note. When a PayPal account is not set up for use with Opayo, then leave the field blank, or set it to 0. You must contact PayPal directly to apply for Reference transactions and confirm the service is live before attempting to pass a value of 1 for repeat payments. |
No |
BOOLEAN |
Flag |
|
CreateToken |
Set this flag to indicate that you want a token generated and stored in our database and returned to you for future use.
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.
Important: In order to store a token, the Credential on File fields must be provided.
Note. To store a Token more than once, a value of 1 must be passed each time the Token is used. |
No |
BOOLEAN |
Flag |
|
BasketXML |
This is optionally used to replace the basket field content. When you use this field you must leave the Basket field empty. |
No |
|
20000 |
|
CustomerXML |
This is optionally used to store additional customer information. For example, for fraud screening. |
No |
|
2000 |
|
VendorData |
This is optionally used to pass any data you want displayed against the transaction in MyOpayo. |
No |
Letters, digits, and spaces
|
200 |
|
ReferrerID |
This is optionally 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 |
The URL this transaction originated from. This is useful for reporting purposes when transactions can originate from more than one website. If you provide a Fully Qualified Domain Name (FQDN), then this will take precedence over any current website or home page URL value displayed in MyOpayo. It is then used in the 3D-Secure authentication request and can be displayed to the cardholder during a challenge authentication. |
No |
RFC1738 |
100 |
|
FIRecipientAcctNumber |
Required for UK merchants who have a merchant category code of 6012 (Financial Institutions) comprising either:
|
No |
Letters and digits
|
10 |
|
FIRecipientSurname |
Required for UK merchants who have a merchant category code of 6012 (Financial Institutions) comprising the Primary Recipient's surname or last name. |
No |
Letters and spaces
|
20 |
|
FIRecipientPostcode |
Required for UK merchants who have a merchant category code of 6012 (Financial Institutions) comprising the Primary Recipient's postcode. |
No |
Letters, digits, and spaces
|
|
|
FIRecipientDoB |
Required for UK merchants who have a merchant category code of 6012 (Financial Institutions) comprising the Primary Recipient's date of birth in the format YYYYMMDD. |
No |
Digits |
8 |
YYYYMMDD |
BrowserJavaEnabled |
Boolean that represents the ability of the cardholder browser to execute JavaScript.
Required when BrowserJavascriptEnabled = 1 |
Yes |
Digits |
|
|
BrowserJavascriptEnabled |
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 |
|
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 |
|
COFUsage |
When the COFUsage field is not used, then:
When you want to use one or more subsequent transactions, or are registering a token alongside this transaction, then the COFUsage value must be FIRST. When a TOKEN is used on this transaction, then the value must be SUBSEQUENT. |
No |
Uppercase letters |
20 |
|
InitiatedType |
This flag indicates whether the customer is in session when the transaction is being taken. |
Conditional |
Uppercase letters |
20 |
MIT CIT |
MITType |
We recommend you always include a MITType value.
Values:
|
Conditional |
Uppercase letters |
20 |
|
RecurringExpiry |
Required when MITType=RECURRING or INSTALMENT. This is the date of the last recurring payment or 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 when MITType=RECURRING or INSTALMENT. This is the regular frequency of the recurring payment or instalment in days. For example, a value of 30 means a frequency of every 30 days.
|
Conditional |
Digits |
4 |
|
PurchaseInstalData |
Required if MITType=INSTALMENT. This is the number of instalments required to complete payment for the received goods or services. This value must be greater than 1. For example, a value of 2 represents their needing to be 2 instalments. 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 |
|
SchemeTraceID |
The unique reference number associated with an authorisation request required when you use a stored Credential on File. It links subsequent payments with the first payment and is returned when you first store a Credential on File. Required if COFUsage=SUBSEQUENT, unless a Token is used. Note: If you’re using a stored credential stored prior to the PSD2 mandated changes, then use the following value: SP999999999 to advise Opayo of this. Once authorised, you’ll receive a new SchemeTraceID value that you can then use going forward. |
Conditional |
ITU-T T.50 value codes. ASCII range in hexadecim al from 20 to 7E (from space to tilde ~) |
56 |
|