You need a user account with the role “Webservices JWT” to create the token. The token should be created and signed on your server.
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:
<header>.<payload>.<signature>
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":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"termurl":"https://payments.securetrading.net/process/payments/mobilesdklistener",
"requesttypedescriptions":["THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}
eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1IiwidGVybXVybCI6Imh0dHBzOi8vcGF5bWVudHMuc2VjdXJldHJhZGluZy5uZXQvcHJvY2Vzcy9wYXltZW50cy9tb2JpbGVzZGtsaXN0ZW5lciIsInJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIiwiQVVUSCJdfSwiaWF0IjoxNTU5MDMzODQ5LCJpc3MiOiJqd3QudXNlciJ9
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 use to sign 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)
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:
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJqd3QudXNlciIsImlhdCI6MTU5NDY0NzI2OCwicGF5bG9hZCI6eyJiYXNlYW1vdW50IjoxMDUwLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1IiwiYWNjb3VudHR5cGVkZXNjcmlwdGlvbiI6IkVDT00ifX0.A6gAnUq2NCSlIiLOcDyzhuo4E8Bm5oPWSKbkjOKKHhc
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:
(Response JWT)
"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1OTQ2NDcyNjgsInBheWxvYWQiOnsicmVxdWVzdHJlZmVyZW5jZSI6Ilc1Ni11YWN3bTU0ayIsInZlcnNpb24iOiIxLjAwIiwiand0IjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBjM01pT2lKcWQzUXVkWE5sY2lJc0ltbGhkQ0k2TVRVNU5EWTBOekkyT0N3aWNHRjViRzloWkNJNmV5SmlZWE5sWVcxdmRXNTBJam94TURVd0xDSmpkWEp5Wlc1amVXbHpiek5oSWpvaVIwSlFJaXdpYzJsMFpYSmxabVZ5Wlc1alpTSTZJblJsYzNSZmMybDBaVEV5TXpRMUlpd2lZV05qYjNWdWRIUjVjR1ZrWlhOamNtbHdkR2x2YmlJNklrVkRUMDBpZlgwLkE2Z0FuVXEyTkNTbElpTE9jRHl6aHVvNEU4Qm01b1BXU0tia2pPS0tIaGMiLCJyZXNwb25zZSI6W3siYXV0aG1ldGhvZCI6IkZJTkFMIiwidHJhbnNhY3Rpb25zdGFydGVkdGltZXN0YW1wIjoiMjAyMC0wNy0xMyAxMzozNDoyOCIsImN1c3RvbWVyb3V0cHV0IjoiUkVTVUxUIiwibGl2ZXN0YXR1cyI6IjAiLCJtZXJjaGFudG5hbWUiOiJNZXJjaGFudCBuYW1lIiwic3BsaXRmaW5hbG51bWJlciI6IjEiLCJkY2NlbmFibGVkIjoiMCIsInNldHRsZWR1ZWRhdGUiOiIyMDIwLTA3LTEzIiwiZXJyb3Jjb2RlIjoiMCIsImNhdnYiOiJZMkZ5WkdsdVlXeGpiMjF0WlhKalpXRjFkR2c9IiwibWVyY2hhbnRudW1iZXIiOiIwMDAwMDAwMCIsIm1lcmNoYW50Y291bnRyeWlzbzJhIjoiR0IiLCJzdGF0dXMiOiJZIiwidHJhbnNhY3Rpb25yZWZlcmVuY2UiOiIxLTItMzQ1Njc5IiwidGhyZWVkdmVyc2lvbiI6IjIuMS4wIiwicGF5bWVudHR5cGVkZXNjcmlwdGlvbiI6Ik1BU1RFUkNBUkQiLCJiYXNlYW1vdW50IjoiMTA1MCIsImVjaSI6IjAyIiwiYWNjb3VudHR5cGVkZXNjcmlwdGlvbiI6IkVDT00iLCJ0aWQiOiIyNzg4Mjc4OCIsImFjcXVpcmVycmVzcG9uc2Vjb2RlIjoiMDAiLCJyZXF1ZXN0dHlwZWRlc2NyaXB0aW9uIjoiQVVUSCIsInNlY3VyaXR5cmVzcG9uc2VzZWN1cml0eWNvZGUiOiIyIiwiY3VycmVuY3lpc28zYSI6IkdCUCIsImF1dGhjb2RlIjoiVEVTVDk1IiwiZXJyb3JtZXNzYWdlIjoiT2siLCJpc3N1ZXJjb3VudHJ5aXNvMmEiOiJaWiIsIm1hc2tlZHBhbiI6IjUyMDAwMCMjIyMjIzEwMDUiLCJzZWN1cml0eXJlc3BvbnNlcG9zdGNvZGUiOiIwIiwiZW5yb2xsZWQiOiJZIiwic2VjdXJpdHlyZXNwb25zZWFkZHJlc3MiOiIwIiwib3BlcmF0b3JuYW1lIjoiand0LnVzZXIiLCJzZXR0bGVzdGF0dXMiOiIwIn1dLCJzZWNyYW5kIjoiZGdjNlFKOEk1In0sImF1ZCI6Imp3dC51c2VyIn0.XE-vjH2RWS7KLItZx6fa0G_A6mcmBAgxdMylP7IAt9w"
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.
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
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:
- Base64URL decode JWT header
- Base64URL decode JWT payload
- Re-generate the signature by re-encoding the header, the payload and signing them with your secret.
(as explained above)
Parse the payload
We provide a parsing utility to extract the payload field data as part of reviewing the payment response fields:
(Kotlin)
val response: PaymentTransactionManager.Response = paymentTransactionManager.executeSession(paymentSession)
//Every JWT returned from the SDK should be verified before further usage.
for (jwt in response.responseJwtList) {
if (!verifyJwtIntegrity(jwt)) {
throw SecurityException("JWT verification failed!")
}
}
val parsedResponse = ResponseParser.parse(response.responseJwtList)
//process parsed response
Response fields
After you receive the response, we recommend you review the information below when handling the customer’s payment session:
Transaction reference
The transactionreference is a unique identifier for the transaction. You will need to record this reference in order to query or perform other actions on this transaction at a later time.
Order reference
The orderreference is a custom identifier for the transaction that we recommend you submit in the JWT payload of each transaction. If your system has been configured to assign orderreference values to your transactions, you can use these to ensure you are checking the correct response following a payment.
Request type
You will need to check the requesttypedescription returned in the response. Only values of “AUTH” indicate the authorisation of a payment. Click here for a full list of different request types supported by Trust Payments.
Error code
You will need to check the errorcode returned to determine the outcome of the transaction:
| Error code | Description | Actions required |
| 0 | Successful transaction. | None. |
| 30000 | Indicates invalid data has been submitted within the payload of the JWT. | Check the fields submitted within the payload of the JWT meet our specification. |
| 60010 60034 99999 |
This can be due to a communication problem with a bank or third party. | We recommend informing the customer of the problem and to contact you to query the issue. You will need to contact our Support Team, providing a copy of the entire request submitted and response returned, and we will contact the relevant parties to establish the status of the request. In the interest of security, ensure you omit or mask sensitive field values, such as card details. |
| 60022 | The customer was prompted for authentication, but failed this part of the process, meaning the transaction was not authorised. | Provide customer with alternative means of payment and allow them to try again. |
| 70000 | Authorisation for the payment was attempted but was declined by the issuing bank. | |
| Other | Click here for a full list of errorcode values that can be returned. | Depends on the errorcode returned. |
Settle status
You will need to check the settlestatus returned in the response:
| Settle status | Description | Actions required |
| 0 | Pending automatic settlement. | None. |
| 1 | Pending manual settlement (overrides fraud / duplicate checks, if enabled). | |
| 2 | Payment authorised but suspended on the Trust Payments system. | Manually investigate the transaction to determine the reason the payment was suspended. If you are okay to proceed, you can update the transaction to allow settlement. |
| 3 | Payment cancelled. | Look at the errorcode to determine the reason the payment was not completed. |
3-D enrolled
The enrolled field will inform you if the customer’s card is enrolled in 3-D Secure:
| 3-D enrolled | Description | Actions required |
| Y | The customer’s card is enrolled. | Handled by the Mobile SDK. |
| N | The customer’s card is not enrolled. | |
| U | Unable to determine if card is enrolled. | |
| B | Merchant authentication rule is triggered to bypass authentication in this use case. |
3-D status
The status field will inform you if the customer was successfully authenticated during the 3-D Secure process:
| 3-D status | Description | Actions required |
| Y | The customer was successfully authenticated. | None. The Mobile SDK will handle these cases automatically. |
| A | Authentication attempted but not completed. | |
| U | Authentication couldn’t be performed. | |
| C | Challenge required for authentication. | |
| N | The customer was not authenticated. The payment will not be processed. |
|
| R | Authentication was rejected. The payment will not be processed. |
3-D version
The version field specifies the version of 3-D Secure used for the payment. The value will start with either “1.x.x” to denote 3-D Secure v1, or “2.x.x” to denote 3-D Secure v2.
JWT Field Specification
| Field | Format | Description | ||
| JWT Payload |
|
|||
| 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. |
||
| iss | Alphanumeric (255) | Your JWT username. | ||
| Payload Object | ||||
| accounttypedescription | Alphanumeric (20) | Value submitted is “ECOM” (represents an e-commerce transaction). | ||
| authmethod | Alphanumeric (5) |
Supported values are: 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. |
||
| billingprefixname | Alphanumeric (25) | The billing name prefix, from the following list: Mr, Mrs, Miss, Dr, Ms, Prof, Rev, Sir, Lord, Lady, Dame & Mx. | ||
| billingfirstname | Alphanumeric (127) |
The billing first name. Required for Visa Secure Data Field Mandate. Required for gaming merchants. |
||
| billingmiddlename | Alphanumeric (127) | The billing middle name. | ||
| billinglastname | Alphanumeric (127) |
The billing last name. Required for Visa Secure Data Field Mandate. Required for gaming merchants. |
||
| billingsuffixname | Alphanumeric (25) | The billing suffix name. | ||
| billingpremise | Alphanumeric (25) |
The house number or first line of the billing address. |
||
| billingstreet | Alphanumeric (127) |
The house number or first line of the billing address. |
||
| billingtown | Alphanumeric (127) |
The town entered for the billing address. |
||
| billingcounty | Alphanumeric (127) |
Billing county.
Note: If submitted, billingcountryiso2a is required. |
||
| billingpostcode | Alphanumeric (25) |
The billing postcode or ZIP code must be valid for the billingcountryiso2a submitted. |
||
|
|
billingcountryiso2a | iso2a |
Billing country in iso2a format.
Required if billingcounty is submitted. Otherwise, Optional. |
|
| billingemail | Email (255) |
Billing email address. Required for Visa Secure Data Field Mandate when billingtelephone is not provided. |
||
| billingtelephone |
Alphanumeric including symbols (20) |
Billing telephone number. Valid characters:
Required for Visa Secure Data Field Mandate when billingemail is not provided. |
||
| billingtelephonetype | Char (1) |
Type of billing phone number:
|
||
| credentialsonfile | Numeric (1) |
The following values can be submitted:
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.
|
||
| customerprefixname | Alphanumeric (25) | Delivery name. | ||
| customerfirstname | Alphanumeric (127) | |||
| customermiddlename | Alphanumeric (127) | |||
| customerlastname | Alphanumeric (127) | |||
| customersuffixname | Alphanumeric (25) | |||
| customerpremise | Alphanumeric (25) |
Delivery address. The delivery postcode or ZIP code must be valid for the customercountryiso2a submitted. |
||
| customerstreet | Alphanumeric (127) | |||
| customertown | Alphanumeric (127) | |||
| customercounty | Alphanumeric (127) | |||
| customercountryiso2a | iso2a | |||
| customerpostcode | Alphanumeric (25) | |||
| customeremail | Email (255) | Delivery email address. | ||
| customertelephone |
Alphanumeric including symbols (20) |
Delivery telephone number. Valid characters:
|
||
| customertelephonetype | Char (1) |
Type of delivery phone number:
|
||
| 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. |
||
| customfield2 | ||||
| customfield3 | ||||
| customfield4 | ||||
| customfield5 | ||||
| currencyiso3a | iso3a |
The currency that the transaction was processed in. |
||
| 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. |
||
|
|
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”.
Please refer to Visa’s own documentation for further information. |
|
| 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:
|
||
| 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. | ||
| 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. |
||
| parenttransactionreference | Alphanumeric including hyphens (25) | Allows you to specify the transactionreference of a previous request. Key details are inherited from this request. | ||
| requesttypedescriptions | List |
The request types to be processed. Important: 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. |
||
|
|
scaexemptionindicator | Numeric (1) |
Used to effect 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:
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:
|
|
| 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: YYYY-MM-DD. |
||
| settlestatus | Numeric (3) |
A numeric value used to define the settlement instruction.
|
||
| sitereference | Alphanumeric (50) | Unique reference that identifies your Trust Payments site. | ||
| subscriptionbegindate | Date YYYY-MM-DD |
Optional when scheduling subscriptions. 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. |
||
| 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:
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) |
Required when scheduling subscriptions. 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) |
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. |
||
| subscriptiontype | Alpha (11) |
Required when scheduling subscriptions. This field indicates the type of subscription to be processed. Your system can submit these two values:
*Installments are 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. |
||
| 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”). |
||
| threedbypasspaymenttypes | 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. | ||
| 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”). |
||
| termurl | URL (1024) |
Required for 3-D Secure authentication. This URL is used to instruct the card issuer where to send the customer’s browser after they have been authenticated on the card issuer’s ACS. You must submit the following URL in this field when performing 3-D Secure: https://payments.securetrading.net/process/payments/mobilesdklistener |
||
| walletsource | Alpha (9) |
Required for Google Pay transactions. Must be submitted with "GOOGLEPAY". |
||
| wallettoken | JSON-encoded string |
Required for Google Pay transactions. Unique token provided by Google to represent the customer’s card details. |
||
