Transaction registration POST

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.

Transaction Registration POST

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

TxType

Transaction Type. This must be in UPPERCASE.

Yes

Uppercase letters

15 

  • PAYMENT

  • DEFERRED

  • AUTHENTICATE

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:

  • No more than 2 decimal places. For example, 5.67.

  • Minimum for no minor unit currencies like JPY is 1.

  • Amounts must be in the UK currency format.

  • The period must be used to indicate the decimal place.  

  • The comma must only be used to separate groups of thousands.

Yes

Digits, periods, and commas

  

 

 

 

 

 

0.01 to 100,000.00

Currency

The transaction currency. This must be supported by one of your Opayo merchant accounts or the transaction will be rejected.

Yes

ISO4217

 

  • GBP

  • EUR

  • USD

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:

  • 3DSv2 supports 2 to 45 characters.

  • Accented characters are not supported.

  • 3DSv1 supports a maximum of 50 characters.

When a cardholder name is between 46 and 50 characters inclusive, then 3DSv2 cannot be performed and 3DSv1 will be performed instead.

Conditional
Not required if CardType=PAYPAL

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  

CardType

  • VISA = Visa

  • MC = MasterCard

  • MCDEBIT = Debit MasterCard

  • DELTA = Visa Debit

  • MAESTRO = Domestic and International issued

  • Maestro

  • UKE = Visa Electron

  • AMEX = American Express

  • DC = Diners Club International and Discover

  • JCB = Japan Credit Bureau

  • PAYPAL

 

Uppercase letters

 

  • VISA

  • MC

  • MCDEBIT

  • DELTA

  • MAESTRO

  • UKE

  • AMEX

  • DC

  • JCB

  • PAYPAL

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

Examples:

  • GB

  • IE

  • DE

BillingState

Mandatory when the BillingCountry is set to US.

Conditional

Valid 2-letter US States

US

Examples:

  • AL

  • MS

  • NY

BillingPhone

The BillingPhone should be formatted with:

  • A leading +

  • Country code less the leading 0

  • Phone number

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

  • GB

  • IE

  • DE

DeliveryState

Mandatory when DeliveryCountry is set to US.

 

Conditional

Valid 2-letter US States

US

Examples:

  • AL

  • MS

  • NY

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: 

  • me@mail1.com

Basket

This Basket content is displayed in MySagePay.

Important. When this field contains a value, you must leave the BasketXML field blank.

Refer to the Basket section

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.

  • 0 = No Gift Aid box displayed (default)

  • 1 = Display Gift Aid box on payment page.

No

BOOLEAN

Flag

  • 0

  • 1

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.

  • 0 = Default value. When AVS/CV2 enabled then check them. If rules apply, use rules.

  • 1 = Force AVS/CV2 checks even when not enabled for the account. If rules apply, use rules.

  • 2 = Force NO AVS/CV2 checks even when enabled on account.

  • 3 = Force AVS/CV2 checks even when not enabled for the account and DON’T apply any rules.

 

Note. This field is ignored for PayPal and European Payment method transactions.

No

Digits

Flag

  • 0

  • 1

  • 2

  • 3

ClientIPAddress

The IPv4 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. We will attempt to Geolocate the IP address in your reports and fraud screening.

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
 

15

 

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.

Notes:

  • 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

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.

  • E = Use the e-commerce merchant account (default).

  • M = Use the mail order/telephone order account (if present).

  • C = Use the continuous authority merchant account (if present).

Note. This field is ignored for PayPal transactions.

No Uppercase letters
1
  • E

  • M

  • C

BillingAgreement

Set this flag to 1 when you want to register this transaction as the first in a series of regular payments.

  • 0 = This is a normal PayPal transaction, not the first in a series of payments (default)

  • 1 = This is the first in a series of PayPal payments. Subsequent payments can be taken using TxType=REPEAT.

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

  • 0

  • 1

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.

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

  • 0 (default)

  • 1

BasketXML

This is optionally used to replace the basket field content. When you use this field you must leave the Basket field empty.

Refer to BasketXML

No

 

20000 

 

CustomerXML

This is optionally used to store additional customer information. For example, for fraud screening.

Refer to CustomerXML

No

 

2000 

 

VendorData

This is optionally used to pass any data you want displayed against the transaction in MySagePay.

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 MySagePay. 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:

  • The first 6 and the last 4 characters of the primary recipient PAN (no spaces), or

  • When the primary recipient account is not a card, up to 10 alphanumeric characters of the account number or,

  • When the primary recipient account is not a card and the account number is less than 10 characters long, the whole account number.

 

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

BrowserJavascriptEnabled

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

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

COFUsage

When the COFUsage field is not used, then:

  • The Transaction Request is classed as a one-off or standalone transaction and the Repeat option is not available in MySagePay.

  • You cannot use TxType=REPEAT for standalone transactions using the shared API.

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 

  • FIRST

  • SUBSEQUENT

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.

  • Required when InitiatedType=MIT.

  • Optional when InitiatedType=CIT.

Values:

  • INSTALMENT = A single purchase of goods/services paid for over multiple payments.

  • RECURRING = A purchase of goods/services provided at fixed regular intervals not exceeding one year between transactions.

  • UNSCHEDULED = A purchase of goods/services provided at irregular intervals with a fixed or variable amount.

  • INCREMENTAL = An additional purchase made after an initial or estimated authorisation. For example, room service is added to the cardholders stay. Only available for certain MCCs, such as Hotels, Car Rental companies.

  • DELAYEDCHARGE = An additional charge made after original services are rendered. For example, a parking fine. Only available for certain MCCs such as Car Rental companies.

  • NOSHOW = A charge for services where the cardholder entered into an agreement to purchase but did not meet the terms of the agreement. For example, a no show after booking a hotel room. Only available for certain MCCs, such as Hotels, Car Rental companies.

  • REAUTHORISATION = A further purchase is made after the original purchase. For example, extended stays/rentals. Can also be used in split shipment scenarios.

  • RESUBMISSION = An authorisation request has been declined due to insufficient funds, DeclineCode=51, at the time the goods or services have already provided. You can resubmit your transaction and attempt to get a successful authorisation.

 

Conditional

Uppercase letters

20 

  • INSTALMENT

  • RECURRING

  • UNSCHEDULED

  • INCREMENTAL

  • DELAYEDCHARGE

  • NOSHOW

  • REAUTHORISATION RESUBMISSION

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

 

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

 

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