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	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.	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	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, accented characters are not supported.	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 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	2	Examples: GB IE DE
BillingState	Mandatory when the BillingCountry is set to US.	Conditional	Valid 2-letter US States US	2	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	2	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 MyOpayo. 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 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. 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 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: 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
BrowserJavaEnabled	Boolean that represents the ability of the cardholder browser to execute JavaScript. 0 = False 1 = True Required when BrowserJavascriptEnabled = 1	Yes	Digits		0 1
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	2	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	2	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 MyOpayo. 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	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