Contents

JSON Web Token

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

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

 


 

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 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 (required when scheduling a subscription). Note: Visa and Mastercard have mandated that you must obtain cardholder consent before storing card details for future use. Click here for further information
  • 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 Either baseamount or mainamount must be included The amount of the transaction in base units (without any decimal places). e.g. £10.50 would be submitted as “1050”
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
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:
YYYY-MM-DD.
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.
subscriptionbegindate Date YYYY-MM-DD 10 Conditional This field refers to the 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.

subscriptionfinalnumber Numeric 5 Conditional 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.

subscriptionfrequency Numeric 11 Conditional Combined with unit, 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

subscriptionnumber Numeric 5 Conditional 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.
subscriptiontype Alpha 11 Conditional 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).

Note: Installments are only accepted by certain acquirers. For further info, please contact your bank.

subscriptionunit Alpha 5 Conditional

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

transactionactive Numeric 1 Conditional 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”).

 

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

Padlock
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 within the app itself.

 

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 when initialising the library.

 


 

Verify the response JWT signature

The outcome of the request processed will be returned in the form of a new JWT. The following is an example of a response returned by Trust Payments:


"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1OTQ2NDcyNjgsInBheWxvYWQiOnsicmVxdWVzdHJlZmVyZW5jZSI6Ilc1Ni11YWN3bTU0ayIsInZlcnNpb24iOiIxLjAwIiwiand0IjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBjM01pT2lKcWQzUXRjR2R6Ylc5aWFXeGxjMlJySWl3aWFXRjBJam94TlRrME5qUTNNalk0TENKd1lYbHNiMkZrSWpwN0luQmhjbVZ1ZEhSeVlXNXpZV04wYVc5dWNtVm1aWEpsYm1ObElqb2lOVFl0T1MweE5ETTBNek1pTENKaVlYTmxZVzF2ZFc1MElqb3hNRFV3TENKamRYSnlaVzVqZVdsemJ6TmhJam9pUjBKUUlpd2ljMmwwWlhKbFptVnlaVzVqWlNJNkluUmxjM1JmY0dkemJXOWlhV3hsYzJSck56azBOVGdpTENKaFkyTnZkVzUwZEhsd1pXUmxjMk55YVhCMGFXOXVJam9pUlVOUFRTSjlmUS53MHc2eGhzaGRMMmY4dm5PRWpXMmZvdHJUZ0lGU0RzZ2lxd3VlU21lbExnIiwicmVzcG9uc2UiOlt7ImF1dGhtZXRob2QiOiJGSU5BTCIsInRyYW5zYWN0aW9uc3RhcnRlZHRpbWVzdGFtcCI6IjIwMjAtMDctMTMgMTM6MzQ6MjgiLCJwYXJlbnR0cmFuc2FjdGlvbnJlZmVyZW5jZSI6IjU2LTktMTQzNDMyIiwiY3VzdG9tZXJvdXRwdXQiOiJSRVNVTFQiLCJsaXZlc3RhdHVzIjoiMCIsIm1lcmNoYW50bmFtZSI6InBncyBtb2JpbGUgc2RrIiwic3BsaXRmaW5hbG51bWJlciI6IjEiLCJkY2NlbmFibGVkIjoiMCIsInNldHRsZWR1ZWRhdGUiOiIyMDIwLTA3LTEzIiwiZXJyb3Jjb2RlIjoiMCIsImNhdnYiOiJZMkZ5WkdsdVlXeGpiMjF0WlhKalpXRjFkR2c9IiwibWVyY2hhbnRudW1iZXIiOiIwMDAwMDAwMCIsIm1lcmNoYW50Y291bnRyeWlzbzJhIjoiR0IiLCJzdGF0dXMiOiJZIiwidHJhbnNhY3Rpb25yZWZlcmVuY2UiOiI1Ni05LTE0MzQzMyIsInRocmVlZHZlcnNpb24iOiIyLjEuMCIsInBheW1lbnR0eXBlZGVzY3JpcHRpb24iOiJNQVNURVJDQVJEIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJlY2kiOiIwMiIsImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwidGlkIjoiMjc4ODI3ODgiLCJhY3F1aXJlcnJlc3BvbnNlY29kZSI6IjAwIiwicmVxdWVzdHR5cGVkZXNjcmlwdGlvbiI6IkFVVEgiLCJzZWN1cml0eXJlc3BvbnNlc2VjdXJpdHljb2RlIjoiMiIsImN1cnJlbmN5aXNvM2EiOiJHQlAiLCJhdXRoY29kZSI6IlRFU1Q5NSIsImVycm9ybWVzc2FnZSI6Ik9rIiwiaXNzdWVyY291bnRyeWlzbzJhIjoiWloiLCJtYXNrZWRwYW4iOiI1MjAwMDAjIyMjIyMxMDA1Iiwic2VjdXJpdHlyZXNwb25zZXBvc3Rjb2RlIjoiMCIsImVucm9sbGVkIjoiWSIsInNlY3VyaXR5cmVzcG9uc2VhZGRyZXNzIjoiMCIsIm9wZXJhdG9ybmFtZSI6Imp3dC1wZ3Ntb2JpbGVzZGsiLCJzZXR0bGVzdGF0dXMiOiIwIn1dLCJzZWNyYW5kIjoiZGdjNlFKOEk1In0sImF1ZCI6Imp3dC1wZ3Ntb2JpbGVzZGsifQ.VFRbxnqcgaitlPSTLbHhpz9Tq-cQZgjk6lp3T9V2FUQ"

 

Info
If an error has occurred, we may not be able to encode the response and, as a result, the response may be only an errorcode and errormessage.

In this scenario, we recommend asking the customer to try the payment again.

e.g. errorcode 50000, errormessage “Timeout”.

 

To view the full response, you will need to decode the JWT returned.

External
We recommend using the libraries found at https://jwt.io to decode the JWT.

The response JWT consists of three parts separated by dots (“.”), in the following format:

Header.Payload.Signature

Warning
Before you can trust the response, you need to check the signature returned matches the value expected. If not, it may have been modified by an unauthorised party.

The signature is hashed using SHA-256, and as such, cannot be decoded. This means that to check the signature is correct, your system will need to re-calculate it using the header and payload returned.
Providing you use the same secret during this process, the recalculated signature should match that returned in the response JWT. In summary:

  1. Base64URL decode JWT header
  2. Base64URL decode JWT payload
  3. Re-generate the signature by re-encoding the header, the payload and signing them with your secret.
    (as explained above)

 


 

Tick
Your progress

Now you have learnt how to handle the JWT for a transaction, you will need initialise the SDK and pass through the JWT to process a payment.

Click here to continue >>>