Generate JWT


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 to generate the JWT.

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




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.



Generating the header

The header consists of two parts:

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

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



Generating the payload

The second part of the token is the payload. This must contain the following required fields:

Tag Format Comment
iat Numeric (17) Time in seconds since Unix epoch. Click here for further information.

The payment must be processed within 15 minutes of this timestamp.

iss Alphanumeric (255) Your JWT username.
payload Dictionary
accounttypedescription Alphanumeric (20) Value submitted is “ECOM” (represents an e-commerce transaction).
currencyiso3a Alphanumeric (3) The currency that the transaction was processed in. Click here for further information.
baseamount Numeric (13) The amount of the transaction in base units (without any decimal places). e.g. £10.50 would be submitted as “1050”.

Either baseamount or mainamount is required.

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

Either baseamount or mainamount is required.

sitereference Alphanumeric (50) Unique reference that identifies your Trust Payments site.


Additional fields can optionally be included in the payload.
Click here for a list of all fields that can be submitted


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:



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



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

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 within the jwt field in your JavaScript call.