Transaction Registration

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.  This will be displayed on the Opayo Server payment page when your customer enters their card details.

Yes

HTML

 

100 

 

NotificationURL

The fully qualified URL (including https:// or https://) that Notification POSTs are sent to.

Yes

RFC1738

 

255 

 

Token

The Token provided during the token registration phase.

No

Letters, digits, hyphens, and curly brackets

   

38 

 

BillingSurname

 

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

 

No

Letters, digits, hyphens, spaces, parentheses, and plus
     

19

 

DeliverySurname

 

 

 

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 

 

CustomerEMail

Your customers email address. 

Note. The current version of the Server integration method does not send confirmation emails to the customer. This field is provided for your records only.

No

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.

No

 

7500 

Refer to the Basket section

AllowGiftAid

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

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

Profile

A profile of LOW returns the simplified payment pages which are designed to run within an iFrame and have only one step and minimal formatting.

Leave blank or use NORMAL to render the default card selection screen.

No

Uppercase letters

10 

  • NORMAL

  • LOW

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

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

  • E

  • M

  • C

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

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 the BasketXML section.

No

 

20000 

 

CustomerXML

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

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 

 

Language

The language that payment pages are presented in.

  • When empty, your customer's default browser language is used.
  • If your customer's language is not supported, then the language supported in the templates will be used.

Our default templates currently support:

  • NL = Dutch

  • EN = English

  • FR = French

  • DE = German

  • PT = Portuguese

  • ES = Spanish

 

No

ISO3166

Examples:

  • EN
  • DE
  • FR

Website

The URL this transaction originated from. This is useful for reporting purposes when transactions can originate from more than one 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

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

 

YYYMMDD

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

You must use the CIT value when using Server integration (as the customer is in session).

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