Contents

Payment Pages field specification

 

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

 

Requirements:

 


 

Required fields

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

Field name Description
sitereference The unique Secure Trading site reference that you receive when you sign up.
currencyiso3a The currency in which the transaction will be processed, using ISO3A format.
mainamount The amount of the transaction should be in main units.

e.g. £123.99 would be submitted like this: 123.99.
Currencies such as Japanese Yen which do not require a decimal place can be submitted without.
e.g. 1000 Yen would be 1000.

version This value will be set to 2.
stprofile 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.

 


 

Billing fields

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

Field name Description
billingprefixname The billing name prefix, from the following list: Mr, Mrs, Miss, Dr, Ms, Prof, Rev, Sir, Lord, Lady, Dame & Mx.
billingfirstname The billing first name.
billingmiddlename The billing middle name.
billinglastname The billing last name.
billingpremise The house number or first line of the billing address.
billingstreet The street entered for the billing address.
billingtown The town entered for the billing address.
billingcounty The county entered for the billing address.

This is displayed as “State code (eg. NY)” on pages with US locale and “County” on other configurations.

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”.
billingpostcode The postcode entered for the billing address.

We perform the following validation for addresses in Great Britain, United States and Canada (where ‘T’ represents text A-Z or a-z and ‘N’ represents numbers 0-9):

Great Britain, United States, Canada and British Forces Post Office (BFPO)

If the country provided is not Great Britain, United States or Canada, or if no country is provided, the postcode field is not validated.

billingcountryiso2a  The country entered for the billing address, using ISO2A format.
billingemail  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).
billingtelephone The billing telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
billingtelephonetype 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:

Field name Description
customerprefixname The customer name prefix, from the following list: Mr, Mrs, Miss, Dr, Ms, Prof, Rev, Sir, Lord, Lady, Dame & Mx.
customerfirstname The customer first name.
customermiddlename The customer middle name.
customerlastname The customer last name.
customerpremise The house number or first line of the customer address.
customerstreet The street entered for the customer address.
customertown The town entered for the customer address.
customercounty The county entered for the customer address.

This is displayed as “State code (eg. NY)” on pages with US locale and “County” on other configurations.

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”.
customerpostcode The postcode entered for the customer address.

We perform the following validation for addresses in Great Britain, United States and Canada (where ‘T’ represents text A-Z or a-z and ‘N’ represents numbers 0-9):

Great Britain, United States, Canada and British Forces Post Office (BFPO)

If the country provided is not Great Britain, United States or Canada, or if no country is provided, the postcode field is not validated.

customercountryiso2a  The country entered for the customer address, using ISO2A format.
customeremail  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).
customertelephone The customer telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
customertelephonetype 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 name Description
settleduedate Use this field to defer settlement until the date specified (in the format YYYY-MM-DD).
settlestatus 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 MyST.

(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 name Description
authmethod To manually override the default auth method specified on your account.
dcctype Click here for information on this field.
locale 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
  • nl_NL = Dutch, The Netherlands
  • no_NO = Norwegian, Norway
  • sv_SE = Swedish, Sweden

Click here for further information on this field.

orderreference Your own reference for the transaction. This can be useful when matching transactions to orders within your system.
operatorname 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 MyST.

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.

paymenttypedescription Allows you to choose the payment method for the transaction when using Workflow B.
requesttypedescriptions Used to specify request types to be processed when Enhanced Post is enabled on your account.
sitesecurity Used to submit the request site security hash in the POST.

 


 

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.

Padlock
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

 


 

Customisation fields

Field name Description
stdefaultprofile Supported values:

  • “st_paymentcardonly”
  • “st_cardonly”
  • “st_iframe_cardonly”

Click here for further information.

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

Click here for further information.

 


 

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 name Description
billingcontactdetailsoverride (Optional) 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.

customercontactdetailsoverride (Optional) 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 name Description
paypaladdressoverride Specify how the delivery address is entered when processing payments with PayPal.
paypallocaleiso2a The language of the PayPal login page. For the country code values that can be submitted, please refer to

https://developer.paypal.com/docs/classic/api/locale_codes/

 


 

Rule fields

Field name Description
allurlnotification This is the URL the notification is sent to following any request, when STR-10 is enabled.
declinedurlredirect This is the URL the customer’s browser is redirected to following a declined transaction, when STR-7 is enabled.
declinedurlnotification This is the URL the notification is sent to following a declined transaction, when STR-9 is enabled.
ruleidentifier Used to enable rules on a request-by-request basis (Multiple fields supported).
stextraurlredirectfields This is used to include additional fields in redirects.
stextraurlnotifyfields This is used to include additional fields in URL notifications.
successfulurlredirect This is the URL the customer’s browser is redirected to following a successful transaction, when STR-6 is enabled.
successfulurlnotification 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 name Description
billingdob The customer’s date of birth. Must be in the format YYYY-MM-DD.
customershippingmethod 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 following fields. Failing to submit these fields may result in the customer being displayed an invalid request error.

Field name Description
customeraccountnumbertype Either “CARD” or “ACCOUNT”.
customeraccountnumber If account number type is “ACCOUNT”, the account holder’s account number.

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

customerdob The account holder’s date of birth.
Must be in the format YYYY-MM-DD.
customerlastname The account holder’s last name.
customerpostcode The account holder’s postcode.

We perform the following validation for addresses in Great Britain, United States and Canada (where ‘T’ represents text A-Z or a-z and ‘N’ represents numbers 0-9):

Great Britain, United States, Canada and British Forces Post Office (BFPO)

If the country provided is not Great Britain, United States or Canada, or if no country is provided, the postcode field is not validated.

 

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 the Support team.

Info
Once you have processed a payment or Account Check containing these required fields, they are automatically included in future re-authorisations and account checks performed in MyST, and passed onto the acquiring bank.

 


 

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

Info
This mandate only applies to merchants with certain acquiring banks. Please contact our Support Team for further information.

 

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

Info
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 name Description
customeraccountnumbertype Either “CARD” or “ACCOUNT”.
customeraccountnumber If account number type is “ACCOUNT”, the account holder’s account number.

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

customerdob The account holder’s date of birth.
Must be in the format YYYY-MM-DD.
customerlastname The account holder’s last name.
customerpostcode The account holder’s postcode.

We perform the following validation for addresses in Great Britain, United States and Canada (where ‘T’ represents text A-Z or a-z and ‘N’ represents numbers 0-9):

Great Britain, United States, Canada and British Forces Post Office (BFPO)

If the country provided is not Great Britain, United States or Canada, or if no country is provided, the postcode field is not validated.

debtrepayment 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)