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:
- The token should contain all fields that you do not want to allow the customer to modify while on your checkout (e.g. the transaction amount).
- The token should not contain any fields that the customer is expected to modify (e.g. their address or contact details).
- We recommend including as many fields as possible. Doing so increases the effectiveness of 3-D Secure checks, which in turn may mean the customer is less likely to be challenged in order to prove their identity during the process.
Tag | Type | Length | Required | Comment | |
iat | Numeric | 17 | Required | Time in seconds since Unix epoch (generated using UTC). | |
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:
|
|
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.
|
|
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:
|
|
currencyiso3a | Alphanumeric | 3 | Required | The currency that the transaction was processed in. | |
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”.
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:
|
|
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: YYYY-MM-DD. |
|
settlestatus | Numeric | 3 | Optional | A numeric value used to define the settlement instruction.
|
|
sitereference | Alphanumeric | 50 | Required | Unique reference that identifies your Trust Payments site. |