JSON Web Token

  Last updated: 


  You need a user account with the role “Webservices JWT” to create the token.

If this user account has not already been provided, please request that one is created for your site(s) by contacting our Support Team.

The jwt field submitted in the form will need to be in the form of a JSON Web Token (JWT), which consists of encoded data.
JSON Web Tokens are an open, industry standard RFC 7519 method for securely transmitting data between two parties.
We recommend using the libraries found at https://jwt.io to generate the JWT.

  The jwt creation must be performed on your backend server to avoid the exposure of sensitive details (i.e. JWT signing secret).

In its compact form, JWT consists of three parts separated by dots (“.”), which are:




Generating the header

The header consists of two parts:

  • alg – The signing algorithm used (we support “HS256”, “HS384” and “HS512”).
  • typ – The type of the token, which is “JWT”.

These need to be Base64URL encoded to form the first part of the JWT. Example:

  • Header – {“alg”:”HS256″,”typ”:”JWT”}
  • Encoded – eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Important: Submitted data must be Base64Url encoded, rather than standard Base64.


Generating the payload

When submitting fields in the payload, please follow the below recommendations:

  • The payload should contain all fields that you do not want to allow the customer to modify (e.g. the transaction amount).
  • The payload should not contain any fields that the customer is allowed to modify while on your checkout (e.g. their address or contact details).

These fields are then Base64URL encoded to form the second part of the JWT. Example:

Payload Encoded

  The baseamount field shown in the payload example above contains a value submitted in base units. This means that the value excludes the decimal point, so £10.50 would be submitted as “1050”.
We allow you to instead submit the mainamount here, if preferred. In this case, the value is submitted in main units (£10.50 would be submitted as “10.50” – notice the decimal point). TODOBelow

  Considerations for Mail Order Telephone Order (MOTO) payloads

  • "accounttypedescription=MOTO" must be submitted.
  • Unlike with ECOM transactions, 3-D Secure is not applicable for MOTO, so you can exclude "THREEDQUERY" from the requesttypedescriptions field when creating your JWT payload.


Generating the signature

The final part of the token is the signature. The signature is used to ensure the token wasn’t modified by the customer before the submitted form reaches Trust Payments.

The signature is created by taking the encoded header, the encoded payload, a “secret” and the algorithm specified in the header, and then signing them.

  The “secret” is a secret passphrase (in string format) you will need to include when signing the JWT. This will need to be agreed with our Support Team prior to the processing of requests to our system.

When storing the value of the “secret” on your system, you must ensure you do so in a secure manner.

The value of the “secret” must not be stored in plain text.

Example – If you wanted to use the HMAC SHA256 algorithm, the signature would be created in the following way:

base64UrlEncode(header) + "." +

The final step is to ensure the signature is Base64URL encoded.

  We do not support the signing of tokens with a private key.


Complete JWT example

The result is three Base64URL strings separated by dots (“.”):

If we take the header, the payload and the signature from the examples above, you would end up with the following JWT:


The full token can then be included when initialising the library, like so:

<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number"></div>
<div id="st-expiration-date"></div>
<div id="st-security-code"></div>
<button type="submit">Pay securely</button>
<script src="<CDN_DOMAIN>"></script>
(function() {
var st = SecureTrading({
jwt : 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1IiwicmVxdWVzdHR5cGVkZXNjcmlwdGlvbnMiOlsiVEhSRUVEUVVFUlkiLCJBVVRIIl19LCJpYXQiOjE1NTkwMzM4NDksImlzcyI6Imp3dC51c2VyIn0.4LR3bv1YPOy1E13OwJGRxuyA7j91P7RUTnolVR2FAS4'

Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.


Updating the JWT during the payment session

There are circumstances where you may wish to configure your system to update the JWT after the initial request, but prior to payment completion.

For example, when the customer is making a donation and are prompted to choose a custom amount. Because the amount needs to be included in the JWT to prevent third party users making unauthorised modifications, you would need to update the JWT during the payment session once the final amount has been established.

Click here for instructions on how to configure this.


JWT Field Specification

  Field Format Description
X1-EN.png JWT Payload  


X1-EN.png iat Numeric (17)

Time in seconds since Unix epoch (generated using UTC). Click here for further info.

The JWT is valid for 1 hour from the time submitted in the iat. Once the JavaScript Library has been initialised with this JWT, the customer then has 15 minutes to complete the transaction.

X1-EN.png iss Alphanumeric (255) Your JWT username.
X1-EN.png Payload Object    
X1-EN.png   accounttypedescription Alphanumeric (20)

For E-Commerce (ECOM) solutions, submit "ECOM" in this field.

For MOTO solutions, submit "MOTO" in this field. Subject to requirements. Contact Support for assistance.

X3-EN.png   authmethod Alphanumeric (5)

The following values are supported:

  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.

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

The billing first name.

Required for Visa Secure Data Field Mandate.

Required for gaming merchants.

X3-EN.png   billingmiddlename Alphanumeric (127) The billing middle name.
X1-EN.png   billinglastname Alphanumeric (127)

The billing last name.

Required for Visa Secure Data Field Mandate.

Required for gaming merchants.

X3-EN.png   billingsuffixname Alphanumeric (25) The billing suffix name.
X3-EN.png   billingpremise Alphanumeric (25)

The house number or first line of the billing address.

X3-EN.png   billingstreet Alphanumeric (127)

The house number or first line of the billing address.

X3-EN.png   billingtown Alphanumeric (127)

The town entered for the billing address.

X3-EN.png   billingcounty Alphanumeric (127)

Billing county.

Note: If submitted, billingcountryiso2a is required.

X3-EN.png   billingpostcode Alphanumeric (25)

The billing postcode or ZIP code must be valid for the billingcountryiso2a submitted.

X2-EN.png   billingcountryiso2a iso2a Billing country in iso2a format.

Required if billingcounty is submitted.

Otherwise, Optional.

X2-EN.png   billingemail Email (255)

Billing email address.

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

X2-EN.png   billingtelephone Alphanumeric including
symbols (20)

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) Type of billing phone number:
  • “H” – Home
  • “M” – Mobile
  • “W” – Work
X2-EN.png   credentialsonfile Numeric (1)

The following values can be submitted:

  • 0 – Not eligible for Credentials on File (CoF), or no intention of re-using credentials at a later time.
  • 1 – Cardholder credentials flagged as available for future use (required when scheduling a subscription). The customer is required to undergo EMV 3DS step up authentication to complete the transaction.
  • 2 – Payment using previously-stored credentials.

This is required for Visa and Mastercard transactions where the merchant is utilising the 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.

  Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use.
X3-EN.png   customerprefixname Alphanumeric (25) Delivery name.
X3-EN.png   customerfirstname Alphanumeric (127)
X3-EN.png   customermiddlename Alphanumeric (127)
X3-EN.png   customerlastname Alphanumeric (127)
X3-EN.png   customersuffixname Alphanumeric (25)
X3-EN.png   customerpremise Alphanumeric (25)

Delivery address.

The delivery postcode or ZIP code must be valid for the customercountryiso2a submitted.

X3-EN.png   customerstreet Alphanumeric (127)
X3-EN.png   customertown Alphanumeric (127)
X3-EN.png   customercounty Alphanumeric (127)
X3-EN.png   customercountryiso2a iso2a
X3-EN.png   customerpostcode Alphanumeric (25)
X3-EN.png   customeremail Email (255) Delivery email address.
X3-EN.png   customertelephone Alphanumeric including
symbols (20)

Delivery telephone number. Valid characters:

  • Numbers 0-9
  • Spaces
  • Special characters: + – ( )
X3-EN.png   customertelephonetype Char (1) Type of delivery phone number:
  • “H” – Home
  • “M” – Mobile
  • “W” – Work
X3-EN.png   customfield1 Alphanumeric (100) These fields allow for the submission and storing of custom data in Trust Payments’ records. This data can be retrieved later by performing a CSV transaction download.


Example use case: You may find it useful for reconciliation to record the sale amount and tip separately in two of these custom fields, as baseamount/mainamount fields are the total of both.

X3-EN.png   customfield2
X3-EN.png   customfield3
X3-EN.png   customfield4
X3-EN.png   customfield5
X1-EN.png   currencyiso3a iso3a

The currency that the transaction was processed in.

Click here for further info.

X1-EN.png   baseamount Numeric (13) Either baseamount or mainamount must be included (not both).

The amount of the transaction in base units (without any decimal places). e.g. £10.50 would be submitted as “1050”

  mainamount Numeric (14) Either baseamount or mainamount must be included (not both).

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

X2-EN.png   initiationreason Char (1)

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.

X3-EN.png   locale Undefined 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)
X3-EN.png   operatorname Alphanumeric (255) 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.
X3-EN.png   orderreference

Alphanumeric (25)

See description on right for further details

Your unique order reference that can be stored on the Trust Payments system.

We strongly recommend you submit an orderreference for each transaction.

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.

X3-EN.png   parenttransactionreference Alphanumeric including hyphens (25) Allows you to specify the transactionreference of a previous request. Key details are inherited from this request.
X1-EN.png   requesttypedescriptions List

The request types to be processed.
To process a 3-D Secure authenticated payment, submit [“THREEDQUERY”,”AUTH”].

Important: For E-Commerce (ECOM) transactions, you must ensure “THREEDQUERY” is submitted in this list when performing transactions, in order to ensure 3-D Secure is processed. This is required by the PSD2 mandate.

To learn more about supported request types, click here.

X2-EN.png   scaexemptionindicator Numeric (1)

Used to affect the nature of 3-D Secure authentication in scenarios where this is permitted.

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

Submit one of the following values when exempting transaction from authentication:

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

  Please contact your acquirer to check you are permitted to apply exemptions before attempting to do so.

Alternatively, submit one of the following values to request step up (challenge) authentication is performed:

  • 13 – Request step up authentication at card issuer's discretion.
  • 14 – Request step up authentication is performed.
X3-EN.png   settleduedate Date YYYY-MM-DD Here you can set which day in the future you wish for your transaction to settle. It must be in the format:
X3-EN.png   settlestatus Numeric (3) A numeric value used to define the settlement instruction.
  • “0” – Automatic (default when no value submitted)
  • “1” – Manual
  • “2” – Suspended
X1-EN.png   sitereference Alphanumeric (50) Unique reference that identifies your Trust Payments site.
X2-EN.png   subscriptionbegindate Date YYYY-MM-DD

Optional when scheduling subscriptions.

This field refers to the date when the first automated payment will be processed. From there onward, we will use the data submitted in the subscriptionunit and subscriptionfrequency fields to automatically process the subscription payments at regular intervals.

e.g. If a subscription request is submitted on 5th January 2018

the interval is 1 MONTH (subscriptionfrequency = 1 and subscriptionunit = MONTH)

and subscriptionbegindate is 2018-01-08,

the first automated payment will be processed on 8th January 2018, and all subsequent payments will be processed on the 8th of each month.

If you do not submit the subscriptionbegindate, we will use the subscriptionunit and subscriptionfrequency fields above to automatically schedule the first automated payment.
e.g. In the same scenario as above, but without submitting the subscriptionbegindate, the first automated payment would be processed on 5th February 2018 (1 MONTH after the original request). All subsequent payments will be processed on the 5th of each month.

X2-EN.png   subscriptionfinalnumber Numeric (5)

Required when scheduling subscriptions.

This is used to set the number of payments to be processed over the course of the subscription:

  • If processing a combined AUTH SUBSCRIPTION request:
    If subscriptionnumber = 1

    and subscriptionfinalnumber = 12
    There will be 12 payments in total (The initial AUTH + 11 subscription payments)
  • If processing a combined ACCOUNTCHECK SUBSCRIPTION request:
    If subscriptionnumber = 1

    and subscriptionfinalnumber = 12
    There will be 11 payments in total (The initial ACCOUNTCHECK + 11 subscription payments)

    (The initial ACCOUNTCHECK counts against the final number)

Note: If the value is “0”, the subscription engine will schedule payments indefinitely until the user manually sets the subscription to Inactive.

X2-EN.png   subscriptionfrequency Numeric (11)

Required when scheduling subscriptions.

Combined with subscriptionunit, the frequency defines how frequently payments are processed.e.g. For one payment every 7 days: subscriptionfrequency = 7 and subscriptionunit = DAY

e.g. For one payment every 2 months: subscriptionfrequency = 2 and subscriptionunit = MONTH

X2-EN.png   subscriptionnumber Numeric (5)

Optional when scheduling subscriptions.

Unless specified otherwise, subscriptions start with subscriptionnumber = 1 by default. The subscriptionnumber is automatically incremented in every subsequent subscription payment until it exceeds the value of the subscriptionfinalnumber field, when no further payments will be attempted. A completed subscription is represented by a subscriptionnumber that is higher than the corresponding subscriptionfinalnumber.

X2-EN.png   subscriptiontype Alpha (11)

Required when scheduling subscriptions.

This field indicates the type of subscription to be processed. Your system can submit these two values:

  • RECURRING is used when the customer is performing a recurring payment for a new product/service each time (for example, a magazine subscription). For most merchants, the subscriptiontype should be set to “RECURRING”.
  • INSTALLMENT is only used in select cases with certain acquirers*. It is designed for when a customer is purchasing a single order, with payment being collected over several installments (for example, paying £100 a month for an order until it has been paid in full).

*INSTALLMENT is supported for 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 this feature is supported before proceeding.

X2-EN.png   subscriptionunit Alpha (5)

Required when scheduling subscriptions.

This field represents the unit of time between each subscription. This can be either “DAY” or “MONTH”.

Note: It is imperative that this field is submitted to the gateway in CAPITALS (“DAY” or “MONTH”).

List In order to comply with PSD2, you must perform 3-D Secure authentication with all supported card-based e-commerce transactions. This is achieved by ensuring THREEDQUERY is included in the requesttypedescriptions list in the JWT payload. However, your solution may encounter circumstances in which 3-D Secure is not required / supported by your acquiring bank. By specifying payment types in the threedbypasspaymenttypes list, 3-D Secure authentication will not be performed for the aforementioned payment types.
X2-EN.png   transactionactive Numeric (1)

Optional when scheduling subscriptions.

The subscription status.

“0” – Inactive: Suspends future payments until manually overridden.

“1” – Active: Schedules subscription payments immediately, bypassing fraud & duplicate checks (if enabled).

“2” – Pending (default): Schedules subscription payments after the AUTH has been settled (settlestatus “100”).


  Your progress

Now you have constructed your payment form, configured the JavaScript Library and included your JWT, we now recommend you configure webhooks to ensure you are notified of transactions processed on your account.

Click here to continue.

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