Payment Pages field specification

  Last updated: 

 

The following fields can be included within the POST submitted from your website to Payment Pages.

 

Requirements:

  • All field names must be submitted in lowercase.
  • Do not submit multiple fields with the same name in a single POST, unless documentation states this is permitted.
  • We recommend that text submitted is encoded in UTF-8.
  • Special characters must be URL-encoded (e.g. “&” should be submitted as “%26”).

 

Required fields

The following fields are required in every POST to Payment Pages:

X2-EN.png
In addition to the reviewing the Required fields specified below, please also take time to review all sections on this article for fields denoted as Conditional. These fields may be required depending on your setup.
  Field Format Description
X1-EN.png sitereference Alphanumeric
& underscore (50)

Identifies your site on the Trust Payments system.

If you do not know your site reference, please contact our Support Team.

X1-EN.png currencyiso3a Alpha (3) The currency in which the transaction will be processed, using ISO3A format.
X1-EN.png mainamount Numeric (14) The amount of the transaction in main units.
Only include the amount value and the decimal place (no commas).
e.g. £10.99 would be submitted as 10.99
Currencies such as Japanese Yen which do not require a decimal place are submitted without. e.g. 1000 Yen would be 1000
X1-EN.png version Numeric (1) This value will be set to 2.
X1-EN.png stprofile

Alphanumeric (20)

  • Lowercase letters only.
  • Punctuation and spaces not permitted.
Used to specify the styling used to render the Payment Pages. When using the default appearance, this is set to “default”.
Click here for further information.
X1-EN.png sitesecurity

Site security hash

Used to submit the request site security hash in the POST.

 

Billing fields

You may also submit the following billing fields in the POST:

  If a billing field submitted exceeds the maximum allowed length (as documented in the table below), a field error will be returned (error code 30000).

  Field Format Description
X3-EN.png billingprefixname Alphanumeric including
symbols (25)
The billing name prefix, from the following list: Mr, Mrs, Miss, Dr, Ms, Prof, Rev, Sir, Lord, Lady, Dame & Mx.
X2-EN.png billingfirstname Alphanumeric including
symbols (127)

The billing first name.

Required for Visa Secure Data Field Mandate.

Required for gaming merchants.

X3-EN.png billingmiddlename Alphanumeric including
symbols (127)
The billing middle name.
X2-EN.png billinglastname Alphanumeric including
symbols (127)

The billing last name.

Required for Visa Secure Data Field Mandate.

Required for gaming merchants.

X3-EN.png billingpremise Alphanumeric including
symbols (25)
The house number or first line of the billing address.
X3-EN.png billingstreet Alphanumeric including
symbols (127)
The street entered for the billing address.
X3-EN.png billingtown Alphanumeric including
symbols (127)
The town entered for the billing address.
X3-EN.png billingcounty Alphanumeric including
symbols (127)

The county entered for the billing address.

This is displayed as “State code (eg. NY)” on pages with "us_US" locale.

For US addresses, the state would be entered in this field.

Valid formats:

  • Preferred: Two character state code, e.g. “NY”.
  • Full state name (no abbreviations), e.g. “New York”.
X3-EN.png billingpostcode Alphanumeric (25) The billing postcode or ZIP code. This must be a valid postcode/ZIP code for the billingcountryiso2a submitted.
X3-EN.png billingcountryiso2a  Alpha (2) The country entered for the billing address, using ISO2A format.
X2-EN.png billingemail  Email (255)

The billing email address. This can then be used for correspondence with the customer. Maximum length of 255 (maximum of 64 characters before the”@” symbol).

Required for Visa Secure Data Field Mandate when billingtelephone is not provided.

X2-EN.png billingtelephone Alphanumeric including
symbols (20)
The billing telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )

Required for Visa Secure Data Field Mandate when billingemail is not provided.

X3-EN.png billingtelephonetype Char (1) The type of telephone number entered. The options available are:
  • H = Home
  • M = Mobile
  • W = Work

 

Customer fields

You may also submit details with regards to an additional address for the customer. This usually relates to the delivery address. These fields are included below:

  If a customer field submitted exceeds the maximum allowed length (as documented in the table below), a field error will be returned (error code 30000).

  Field Format Description
X3-EN.png customerprefixname Alphanumeric including
symbols (25)
The customer name prefix, from the following list: Mr, Mrs, Miss, Dr, Ms, Prof, Rev, Sir, Lord, Lady, Dame & Mx.
X3-EN.png customerfirstname Alphanumeric including
symbols (127)
The customer first name.
X3-EN.png customermiddlename Alphanumeric including
symbols (127)
The customer middle name.
X3-EN.png customerlastname Alphanumeric including
symbols (127)
The customer last name.
X3-EN.png customerpremise Alphanumeric including
symbols (25)
The house number or first line of the customer address.
X3-EN.png customerstreet Alphanumeric including
symbols (127)
The street entered for the customer address.
X3-EN.png customertown Alphanumeric including
symbols (127)
The town entered for the customer address.
X3-EN.png customercounty Alphanumeric including
symbols (127)

The county entered for the customer address.

This is displayed as “State code (eg. NY)” on pages with "us_US" locale.

For US addresses, the state would be entered in this field.

Valid formats:

  • Preferred: Two character state code, e.g. “NY”.
  • Full state name (no abbreviations), e.g. “New York”.
X2-EN.png customerpostcode Alphanumeric (25)

The customer’s postcode or ZIP code. This must be a valid postcode/ZIP code for the customercountryiso2a submitted.

Required if Merchant Category Code (MCC) is 6012.

X2-EN.png customercountryiso2a  Alpha (2)

The country entered for the customer address, using ISO2A format.

Required if Merchant Category Code (MCC) is 6012.

X3-EN.png customeremail  Email (255) The customer email address. This can then be used for correspondence with the customer. Maximum length of 255 (maximum of 64 characters before the”@” symbol).
X3-EN.png customertelephone Alphanumeric including
symbols (20)
The customer telephone number. Valid characters:
  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
X3-EN.png customertelephonetype Char (1) The type of telephone number entered. The options available are:
  • H = Home
  • M = Mobile
  • W = Work

 

Settlement fields

You can include the following optional fields in the POST to affect settlement.

  Field Format Description
X3-EN.png settleduedate Date YYYY-MM-DD Use this field to defer settlement until the date specified
(in the format YYYY-MM-DD).
X3-EN.png settlestatus Numeric (3) Leave blank or submit “0” to opt for standard settlement behaviour.

Submit “1” to override Fraud and Duplicate checks, if these have been enabled on your account.

Submit “2” to manually suspend settlement. The transaction will remain in a suspended state until you update the settle status at a later date using Portal.

(Only supported by select acquirers) Submit “100” to settle the transaction immediately after authorisation. Contact the Support Team to check if your acquirer supports this.

 

Charset

In order for data to be transmitted, the customer’s browser encodes it using a character encoding. Our servers need to know this encoding (or charset) in order to correctly decode the data. Many browsers do not provide this information, in which case we will assume the character encoding is ISO-8859-1. This is compatible with all browsers but can result in some characters (especially non-western characters) being interpreted incorrectly.

You can tell the browser to specify the correct charset by including a hidden field “_charset_” within your HTML form. Browsers will automatically fill the value of this field with the charset they are using, so there is no need to specify a value for this field, for example:

<INPUT TYPE=hidden NAME="_charset_" />

 

Request fields

  Field Format Description
X3-EN.png authmethod Alpha (11)

To manually override the default auth method specified on your account. Supported values are:

  The contents of authmethod do not affect the settlement status of the transaction. Settlement status can be controlled using settlestatus and settleduedate. Click here to learn more about the settlement process.

X2-EN.png credentialsonfile Numeric (1)

Required when storing payment credentials for future transactions.

For customers processing a transaction for the first time on your site, you will need to include credentialsonfile=1 if payment credentials are to be stored for future transactions.

Click here to learn more.

X2-EN.png dcctype Alpha (3)

Required when performing DCC transactions.

Click here to learn more about DCC.

X3-EN.png locale Alphanumeric including
underscores (5)
By default, Payment Pages will be displayed to the customer in UK English, unless overridden using the values below:
  • cy_GB = Welsh, United Kingdom
  • da_DK = Danish, Denmark
  • de_DE = German, Germany
  • en_US = English, United States
  • en_GB = English, United Kingdom
  • es_ES = Spanish, Spain
  • fr_FR = French, France
  • it_IT = Italian, Italy
  • nl_NL = Dutch, The Netherlands
  • no_NO = Norwegian, Norway
  • sv_SE = Swedish, Sweden

Click here for further information on this field.

X3-EN.png orderreference

Alphanumeric including
symbols (25)

Recommended length 25 characters or less (exact length dependent on acquiring bank).

Failure to adhere to this requirement may result in the text being truncated in the transaction.

Your own reference for the transaction. This can be useful when matching transactions to orders within your system.

  When including the orderreference in your site security hash, only alphanumeric characters and the following special characters are supported:

~ ! # $ % ^ & * ( ) _ { } [ ] < > , ?

X3-EN.png operatorname Alphanumeric (255)

You can use this field to record the name of the operator performing the payment via the Payment Pages. This is stored in our records and can be viewed later in Portal.

If not submitted in the POST, this value defaults to “paymentpages”.

This value is not displayed on the Payment Pages (providing the account type is “ECOM”).

If you opt to submit the operatorname, we recommend that you update your site security hash to include this field, by contacting our Support Team.

X3-EN.png paymenttypedescription Alpha (20) Allows you to choose the payment method for the transaction when using Journey B.
X3-EN.png requesttypedescriptions Alpha (20) Used to specify request types to be processed when Enhanced Post is enabled on your account.
X3-EN.png scaexemptionindicator Numeric (1) Used to bypass 3-D Secure authentication in certain scenarios where this is permitted. Subject to conditions – click here to learn more.

Note: Only supported by certain acquiring banks. Contact our Support Team for further information.

Please contact your acquiring bank and check you are permitted to apply exemptions before updating your requests to do so.

Submit one of the following values:

  • 1 – Low value
  • 2 – Transaction Risk Analysis
  • 3 – Trusted Merchant
  • 4 – Secure Corporate payment
  • 5 – Delegated authentication

 

Custom fields

You can pass through custom fields in your POST. The field names do not need to be a specific case and will not be saved in the database. No additional configuration is required.

Custom fields can be posted back to your system after a transaction has been processed, by including them in a redirect and/or configuring a URL notification.

  While custom fields do not have a specification on valid values, it is important to ensure the value cannot be hijacked as part of a malicious attack. Wherever possible we recommend the following:

  • Use standard letters and numbers within the ASCII character set without any special characters where possible, particularly with the field names.
  • Any file references you may define should use a full path rather than a relative path.
  • Keep fields and values as short as possible.

Additional considerations

  • The maximum allowed length of custom fieldnames that can be submitted is 100 characters. Any custom fieldnames exceeding this limit will be truncated or cause an error.
  • Fieldnames should not end with “_html”.

 

Customisation fields

  Field Format Description
X3-EN.png stdefaultprofile Alpha and underscores (20) Supported values:
  • “st_paymentcardonly”
  • “st_cardonly”
  • “st_iframe_cardonly”

Click here for further information.

X2-EN.png strequiredfields

Alpha

Specify fields required to be entered by the customer (Multiple fields supported).

Required for Visa Secure Data Field Mandate.

Learn more about the mandate  Learn more about strequiredfields

 

Apple Pay fields

You can submit the following optional fields in your POST to change how the customer is prompted for their address details while on the Payment Pages:

  Field Format Description
X3-EN.png billingcontactdetailsoverride Numeric (1) The billing address for the payment: 
  • “0” –   Uses details entered (or posted) on the Payment Pages.
  • “1” –   Uses details specified on the customer’s Apple Pay account.

If left blank, the address entered (or posted) on Payment Pages is used.

X3-EN.png customercontactdetailsoverride Numeric (1) The customer (delivery) address for the payment:
  • “0” –   Uses details entered (or posted) on the Payment Pages.
  • “1” –   Uses details specified on the customer’s Apple Pay account.

If left blank, the address entered (or posted) on Payment Pages is used.

 

PayPal fields

  Field Format Description
X3-EN.png paypaladdressoverride Numeric (1) Specify how the delivery address is entered when processing payments with PayPal. When utilising the PayPal address override functionality, other delivery fields may be required in certain scenarios. Click here to learn more.
X3-EN.png paypallocaleiso2a Alpha (2) Use this field to localise the content displayed on the PayPal checkout. For a full list of supported values that can be submitted in this field (e.g. paypallocaleiso2a=GB for the UK), please refer to   PayPal’s documentation (link to external site).

 

Rule fields

  Field Format Description
X3-EN.png allurlnotification

URL
Domain max length 75

This is the URL the notification is sent to following any request, when STR-10 is enabled.
X3-EN.png declinedurlredirect

URL
Domain max length 75

This is the URL the customer’s browser is redirected to following a declined transaction, when STR-7 is enabled.
X3-EN.png declinedurlnotification

URL
Domain max length 75

This is the URL the notification is sent to following a declined transaction, when STR-9 is enabled.
X3-EN.png ruleidentifier Alphanumeric and hyphens Used to enable rules on a request-by-request basis (Multiple fields supported).
X3-EN.png stextraurlredirectfields Alpha This is used to include additional fields in redirects.
X3-EN.png stextraurlnotifyfields Alpha This is used to include additional fields in URL notifications.
X3-EN.png successfulurlredirect URL
Domain max length 75
This is the URL the customer’s browser is redirected to following a successful transaction, when STR-6 is enabled.
X3-EN.png successfulurlnotification

URL
Domain max length 75

This is the URL the notification is sent to following a successful transaction, when STR-8 is enabled.

 

Protect Plus fields

The following optional fields can be posted to the Payment Pages to improve the Protect Plus checks:

  Field Format Description
X3-EN.png billingdob Date YYYY-MM-DD The customer’s date of birth. Must be in the format YYYY-MM-DD.
X3-EN.png customershippingmethod Char (1) The shipping method. Can be one of the following values:
  • C      Low Cost
  • D      Designated by Customer
  • I       International
  • M     Military
  • N      Next Day/Overnight
  • O     Other
  • P      Store Pickup
  • T      2 day Service
  • W     3 day Service

 

Merchant Category Code (MCC) 6012 fields

Visa and Mastercard have mandated that all UK-based merchants with a Merchant Category Code (MCC) of 6012 are required to send the addrional fields. Failing to submit these fields may result in the customer being displayed an invalid request error.

  Learn more about MCC 6012

 

Debt repayment fields

Visa and Mastercard have mandated that all merchants processing debt repayments submit the following fields in the POST (when the data has been made available).

  This mandate applies to merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check if this mandate applies to your solution.

Requirement: Your merchant category code must be either 6012, 6051 or 7299.

  Your Merchant Category Code (MCC) is a four-digit number assigned to you by your acquirer. It is used to classify the business by the type of products or services it provides. If you are unsure of the value of your merchant category code, please contact our Support Team.

  Field Format Description
X2-EN.png customeraccountnumbertype Alpha (7)

Either “CARD” or “ACCOUNT”.

Required if performing debt repayment and other conditions described above have been met.

X2-EN.png customeraccountnumber Numeric (20)

If account number type is “ACCOUNT”, the account holder’s account number.

If account number type is “CARD”, the account holder’s card number.

Required if performing debt repayment and other conditions described above have been met.

X2-EN.png customerdob Date YYYY-MM-DD

The account holder’s date of birth.
Must be in the format YYYY-MM-DD.

Required if performing debt repayment and other conditions described above have been met.

X2-EN.png customerlastname Alphanumeric including
symbols (127)

The account holder’s last name.

Required if performing debt repayment and other conditions described above have been met.

X2-EN.png customerpostcode Alphanumeric (25)

The account holder’s postcode or ZIP code.

Required if performing debt repayment and other conditions described above have been met.

X2-EN.png debtrepayment Numeric (1) Indicates if transaction is flagged as debt repayment:
  • 1 – Transaction is flagged as debt repayment.
  • 0 – Transaction is not flagged as debt repayment.

Note: Your site can be configured to automatically submit this flag with value 0 or 1 in every transaction by default. (You can contact our Support Team to make this change)

Required if performing debt repayment and other conditions described above have been met.

Was this article helpful?
0 out of 0 found this helpful