Fields that can be submitted in the payload


The following are a list of fields that can be submitted in the payload (as described in our JWT documentation). When submitting optional fields, please follow the below recommendations:


Tag Type Length Required Comment
iat Numeric 17 Required Time in seconds since Unix epoch (generated using UTC).

Click here for further info.

iss Alphanumeric 255 Required Your JWT username.
payload Required
accounttypedescription Alphanumeric 20 Required Value submitted is “ECOM” (represents an e-commerce transaction).
authmethod Alphanumeric 5 Optional Click here for further info.
billingprefixname Alphanumeric 25 Optional Billing name.
billingfirstname Alphanumeric 127 Optional
billingmiddlename Alphanumeric 127 Optional
billinglastname Alphanumeric 127 Optional
billingsuffixname Alphanumeric 25 Optional
billingpremise Alphanumeric 25 Optional Billing address.
billingstreet Alphanumeric 127 Optional
billingtown Alphanumeric 127 Optional
billingpostcode Alphanumeric 25 Optional
billingcounty Alphanumeric 127 Optional Billing county.

Note: If submitted, billingcountryiso2a is required.

billingcountryiso2a Alphanumeric 2 Conditional Billing country in iso2a format.

Required if billingcounty is submitted.

Otherwise, Optional.

billingemail Alphanumeric 255 Optional Billing email address.
billingtelephone Alphanumeric 20 Optional Billing telephone number.
billingtelephonetype Alphanumeric 1 Optional Type of billing phone number:

  • “H” – Home
  • “M” – Mobile
  • “W” – Work
credentialsonfile Numeric 1 Conditional This is required for Visa and Mastercard transactions where the merchant is utilising the Credentials on File (CoF) feature. If the transaction is not eligible for CoF, or you do not wish to use credentials for future transactions, you can omit this field.


The allowed values for this field are 0, 1 & 2.

  • 0 – Not eligible for CoF, or no intention of re-using credentials at a later time.
  • 1 – Transaction credentials flagged as available for future use.
  • 2 – Payment using previously-stored credentials.
customerprefixname Alphanumeric 25 Optional Delivery name.
customerfirstname Alphanumeric 127 Optional
customermiddlename Alphanumeric 127 Optional
customerlastname Alphanumeric 127 Optional
customersuffixname Alphanumeric 25 Optional
customerpremise Alphanumeric 25 Optional Delivery address.
customerstreet Alphanumeric 127 Optional
customertown Alphanumeric 127 Optional
customercounty Alphanumeric 127 Optional
customercountryiso2a Alphanumeric 2 Optional
customerpostcode Alphanumeric 25 Optional
customeremail Alphanumeric 255 Optional Delivery email address.
customertelephone Alphanumeric 20 Optional Delivery telephone number.
customertelephonetype Alphanumeric 1 Optional Type of delivery phone number:

  • “H” – Home
  • “M” – Mobile
  • “W” – Work
currencyiso3a Alphanumeric 3 Required The currency that the transaction was processed in.

Click here for further info.

baseamount Numeric 13 Required The amount of the transaction in base units (without any decimal places). e.g. £10.50 would be submitted as “1050”
mainamount Numeric 14 Required 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

initiationreason Alphanumeric 1 Conditional This is required when processing a Merchant Initiated Transaction (MIT).


Allows you to assign a reason for the transaction.


Do not submit when processing a Customer Initiated Transaction (CIT).


The allowed values for this field are “A”, “C”, “D”, “S” and “X”.


  • “A” – Reauthorisation
  • “C” – Unscheduled payment
  • “D” – Delayed Charges
  • “S” – Resubmission
  • “X” – No-show (for a hotel booking)


Please refer to Visa’s own documentation for further information.

locale Alphanumeric Undefined Optional By default, the checkout form and any error messages displayed will be rendered in British English. But this behaviour can be overridden by submitting the following locale values in the payload:

  • ‘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)
operatorname Alphanumeric 255 Optional The value of this field contains the name of the user that processed the request. This is optional. If omitted, the value of the alias will be recorded instead, which will either be your site reference or Web Services username, depending on your configuration.
orderreference Alphanumeric 255 Optional Your unique order reference that can be stored on the Trust Payments system.
parenttransactionreference Alphanumeric Alphanumeric including hyphens Optional Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
settleduedate Alphanumeric 10 Optional Here you can set which day in the future you wish for your transaction to settle. It must be in the format:
settlestatus Numeric 3 Optional A numeric value used to define the settlement instruction.

  • “0” – Automatic (default when no value submitted)
  • “1” – Manual
  • “2” – Suspended
sitereference Alphanumeric 50 Required Unique reference that identifies your Trust Payments site.