Contents

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.

URL
We recommend using the libraries found at https://jwt.io to generate the JWT.

 

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

 


 

Requirements

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:


{"alg":"HS256","typ":"JWT"}
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9

Warning
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 Type Length 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
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. e.g. £10.50 would be submitted as “10.50”.

Either baseamount or mainamount is required.

sitereference Alphanumeric 50 Unique reference that identifies your Secure Trading site.

 

Additional fields can optionally be included in the payload.

Click here for a list of all fields that can be submitted

 

Info
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":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345"},"iat":1559033849,"iss":"jwt.user"}
eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1In0sImlhdCI6MTU1OTAzMzg0OSwiaXNzIjoiand0LnVzZXIifQ

Info
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 Secure Trading.

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.

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

 

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


HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

Info
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:


eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1In0sImlhdCI6MTU1OTAzMzg0OSwiaXNzIjoiand0LnVzZXIifQ.RI6FUGp4fehJyhxhy2hib2UO2pluqU4AXqz1l1lRJcY

The full token can then be included within the jwt field in your JavaScript call.