Crypt field

The Crypt field should contain all the other transaction information in plain text as Name=Value fields separated by ‘&’ characters.

You must ensure:

  1. All mandatory fields are present.
  2. There are no spaces after the ‘&’ characters.

Encryption

The string must be encrypted using AES (block size 128-bit) in CBC mode with PKCS#5 padding. Use the provided password as both the key and initialisation vector and encode the result in hex (making sure the letters are in upper case).

  • Prepend the ‘@’ sign to the beginning of the encoded result.
  • To decrypt, ensure you remove the ‘@’ sign before using the same procedure in decryption mode.

Crypt Field Description Table

Name

Description

Mandatory

Valid Characters

Max Length

Allowed Values

VendorTxCode

This should be your own reference code to the transaction. Your site should provide a completely unique VendorTxCode for each transaction.

Yes

Letters, digits, hyphens, periods, underscores, and curly brackets
     

40

 

Amount

Amount for the transaction containing minor digits formatted to two decimal places where appropriate.

For example, 5.10 or 3.29.

Values such as 3.235 will be rejected. 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 currency the transaction is performed in. This must be supported by one of your Opayo merchant accounts or the transaction will be rejected.

Yes

Letters

3

Examples:

  • EUR
  • GBP
  • USD

Description

Free form text description of goods or services being purchased.

This text will be displayed on the Opayo payment page as the customer enters their card details.

Yes

HTML

100

 

SuccessURL

This should be the fully qualified URL (including http:// or https:// header).

It is the URL of the page or script to which the user is redirected if the transaction is successful.

You may attach parameters if you wish. Opayo Form will also send an encrypted field containing important information appended to this URL (see below).

Yes

RFC532N

2000

 

FailureURL

This should be the fully qualified URL (including http:// or https:// header).

It is the URL of the page or script to which the user is redirected if the transaction is not successful, aborted, or if an error occurs.

You may attach parameters if you wish. Opayo Form will also send an encrypted field containing important information appended to this URL (see below).

Yes

RFC532N

2000

 

CustomerName

If provided, the customer’s name will be included in the confirmation emails and stored in MySagePay.

No

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, and spaces
         

100

 

CustomerEMail

If provided, the customer will be emailed on completion of a successful transaction (but not an unsuccessful one).

No

RFC532N

80

 

VendorEMail

If provided, an email will be sent to this address when each transaction completes (successfully or otherwise).

If you wish to use multiple email addresses, you should add them using the ‘:’ (colon) character as a separator. For example, me@mail1.com:me@mail2.com

No

RFC532N

255

 

SendEMail

0 = Do not send either customer or vendor emails

1 = Send customer and vendor emails if addresses are provided

2 = Send vendor email but NOT the customer email

If you do not supply this field, 1 is assumed and emails are sent if addresses are provided.

No

Digits

Flag

  • 0
  • 1
  • 2

EmailMessage

A message to the customer which is inserted into the successful transaction emails only.

If provided, this message is included at the top of the customer confirmation emails.

No

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, and spaces
         

7500

 

BillingSurname

The customer billing details.

All mandatory fields must contain a value, apart from the BillingPostcode. The BillingPostcode can be blank for countries that do not have postcodes (for example, Ireland) but it is required in all countries that do have them.

Providing a blank field when information is required will cause an error.

The BillingState becomes mandatory when the BillingCountry is set to ‘US.’

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, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

50

 

BillingAddress2

No

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

50

 

BillingAddress3

No

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

50

 

BillingCity

Yes

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

40

 

BillingPostCode

Yes

Letters, digits, hyphens, and spaces
   

10

 

BillingCountry

Yes

ISO3166

2

Examples:

  • DE
  • IE
  • GB

 

BillingState

No

Uppercase letters

2

Examples:

  • AL
  • MS
  • NY

BillingPhone

No

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

19

 

DeliverySurname

The customer delivery details.

All mandatory fields must contain a value, apart from the DeliveryPostcode. The DeliveryPostcode can be blank for countries that do not have postcodes (for example, Ireland) but it is required in all countries that do have them. Providing a blank field when information is required will cause an error.

The DeliveryState becomes mandatory when the DeliveryCountry is set to ‘US.’

Yes

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, and spaces
         

20

 

DeliveryFirstnames

Yes

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, and spaces
         

20

 

DeliveryAddress1

Yes

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

50

 

DeliveryAddress2

No

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

50

 

DeliveryAddress3

 

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

50

 

DeliveryCity

Yes

Letters including accents, digits, ampersand, comma, apostrophes, forward and back slashes, hyphens, periods, spaces, colons, parentheses, and CR/LF
            

40

 

DeliveryPostCode

Yes

Letters, digits, hyphens, and spaces
   

10

 

DeliveryCountry

Yes

ISO3166

2

Examples:

  • DE
  • IE
  • GB

DeliveryState

No

Uppercase letters

2

Examples:

  • AL
  • MS
  • NY

DeliveryPhone

No

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

19

 

Basket

You can use the Basket field to supply details of the customer’s order.

This information will be displayed to you in MySagePay. If this field is supplied, then the BasketXML field should not be supplied.

No

 

7500

 

AllowGiftAid

This flag allows the gift aid acceptance box to appear for this transaction on the payment page. This only appears if 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 (default)
  • 1

ApplyAVSCV2

Using this flag, you can fine tune the AVS/CV2 checks and rule set you have defined at a transaction level.

This is useful in circumstances where direct and trusted customer contact has been established and you wish to override the default security checks.

0 = If AVS/CV2 enabled then check them. If rules apply, use rules (default)

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

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

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

This field is ignored for PayPal transactions.

No

Digits

Flag

  • 0(default)
  • 1
  • 2
  • 3

Apply3DSecure

Using this flag, you can fine tune the 3D Secure checks and rule set you’ve defined at a transaction level.

The field is ignored for PayPal transactions.

This is useful in circumstances where direct and trusted customer contact has been established and you wish to override the default security checks.

  • 0 = If 3D-Secure checks are possible and rules allow, perform the checks and apply the authorisation rules. (default)
  • 1 = Force 3D-Secure challenge flow if possible and apply rules for authorisation.
  • 2 = Do not perform 3D-Secure checks for this transaction and always authorise.
Note: This should not be used unless you provide a valid SCA Exemption reason ThreeDSExemptionIndicator.
  • 3 = Force 3D-Secure checks for this transaction if possible but ALWAYS send for authorisation, irrespective of rule base and if the cardholder has failed authentication.
Note: Since the SCA mandate, it is not advisable to 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.

 

No

Digits

Flag

  • 0 (default)
  • 1
  • 2
  • 3

BasketXML

A more flexible version of the current basket field which can be used instead of the basket field.

If this field is supplied then the Basket field should not be supplied.

No

 

20000

 

CustomerXML

This can be used to supply information on the customer for purposes such as fraud screening.

No

 

2000

 

VendorData

Use this field to pass any data you wish to be displayed against the transaction in MySagePay.

No

Letters, digits, and spaces

  

200

 

ReferrerID

This can be 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 the customer sees the payment pages in is determined by the code sent here.

If this is not supplied, then the language default of the shopper’s browser will be used.

If the language is not supported, then the language supported in the templates will be used.

Supported languages in the Default templates are:

  • Dutch
  • English
  • French
  • German
  • Portuguese
  • Spanish

No

ISO3166

2

Examples:

  • DE
  • EN
  • FR

Website

Reference to the website this transaction came from. This field is useful if transactions can originate from more than one website.

Supplying this information will enable reporting to be performed by 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

This should either be the first 6 and the last four characters of the primary recipient PAN (no spaces).

Where the primary recipient account is not a card this will contain up to 10 characters of the account number (alphanumeric), unless the account number is less than 10 characters long in which case the account number will be present in its entirety.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Letters and digits

 

10

 

FIRecipientSurname

This is the surname of the primary recipient.

No special characters such as apostrophes or hyphens are permitted.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Letters and spaces

 

20

 

FIRecipientPostcode

This is the postcode of the primary recipient.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Letters, digits, and spaces

  

?

 

FIRecipientDoB

This is the date of birth of the primary recipient in the format YYYYMMDD.

This field is only required for UK merchants who have a merchant category code of 6012 (Financial Institutions).

No

Digits

 

 

ThreeDSRequestor-AuthenticationInfoXML

Information about 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

Information about 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?

No

 

Object

 

AcctInfoXML

Additional information about the cardholder’s account that has been provided by you.

For example, how long has the cardholder had the account on your website?

No

 

Object

 

AcctID

The account ID, if applicable, of your customer’s account on your website.

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, is this a first-time order or reorder?

No

 

Object

 

TransType

Identifies the type of transaction being authenticated.

  • 01 = 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: If you do not send TransType, the default value of 01 (Goods/Service Purchase) will be used.

No

Digits

2

  • 01
  • 03
  • 10
  • 11
  • 28

ThreeDSExemptionIndicator

Required if Apply3DSecure=2

  • 01 = Low Value Transaction (LVT)
  • 02 = TRA exemption
  • 03 = Trusted beneficiaries exemption
  • 04 = Secure corporate payment
  • 05 = Delegated authentication
  • 0699 Reserved for future use

Learn more about SCA Exceptions.

Conditional

Digits 01 to 99

2

  • 01
  • 02
  • 03
  • 04
  • 05

COFUsage

When the COFUsage field is not used, then all transaction requests will be classed as one-off transactions (standalone transactions).

The Repeat option will not be available in MySagePay and you cannot use TxType=REPEAT for standalone transactions.

Important: When you want to use subsequent transactions, you must submit this field with the value FIRST.

No

Uppercase letters

20

  • FIRST
  • SUBSEQUENT

InitiatedType

This value will always need to be submitted as CIT for a Form integration (as the customer is always in session).

Conditional

Uppercase letters

20

  • CIT
  • MIT

 

MITType

You can resubmit your transaction and attempt to get a successful authorisation.

  • Required if InitiatedType=MIT.
  • Optional if InitiatedType=CIT.
Note: We advise you always include a MITType value.
  • INSTALMENT = A single purchase of goods or services paid for over multiple payments.
  • RECURRING = A purchase of goods or services provided at fixed regular intervals not exceeding one year between transactions.
  • UNSCHEDULED = A purchase of goods or 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. This is only available for certain MCCs, such as hotels and car rental companies.
  • DELAYEDCHARGE = An additional charge made after original services are rendered. For example; a parking fine. This is 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. This is only available for certain MCCs, such as hotels and car rental companies.
  • REAUTHORISATION = A further purchase is made after the original purchase. For example; extended stays or rentals. This 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.

Conditional

Uppercase letters

20

  • DELAYEDCHARGE
  • INCREMENTAL
  • INSTALMENT
  • NOSHOW
  • REAUTHORISATION
  • RECURRING
  • RESUBMISSION
  • UNSCHEDULED

RecurringExpiry

The date of the last recurring payment or instalment.

Required if MITType=RECURRING or INSTALMENT

Note: Submitting a recurring transaction after the declared recurring expiry date may lead to the card issuer declining the transaction request.

Conditional

Digits and hyphens
  

10

YYYY-MM-DD

RecurringFrequency

The regular frequency of the recurring payment or instalment. This value is listed in days. For example; 30 (30 days).

Required if MITType=RECURRING or INSTALMENT

Conditional

Digits

4

 

PurchaseInstalData

The number of instalments required to fully pay off the received goods or services. This value must be greater than 1. For example, 2 (two instalments).

Required if MITType=INSTALMENT

Note: Once the declared number of instalments have passed, any extra instalments taken may lead to the card issuer declining the transaction request.

Conditional

Digits

3