Handling the response

After the customer has submitted the form to the “st.js”, authentication will be performed, followed by the payment. The result will be added to the form (with id=“st-form“), which will then be posted directly to your server, in the format of an application/x-www-form-urlencoded POST.

The response will be sent in the form of a new JWT.

The following is an example of a response returned by Trust Payments:

Token

"jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE1NjE1NDkwNzYsInBheWxvYWQiOnsicmVxdWVzdHJlZmVyZW5jZSI6Ilc0Mi00ZnE0NWNiMCIsInZlcnNpb24iOiIxLjAwIiwicmVzcG9uc2UiOlt7InRyYW5zYWN0aW9uc3RhcnRlZHRpbWVzdGFtcCI6IjIwMTktMDYtMjYgMTE6Mzc6NTYiLCJwYXJlbnR0cmFuc2FjdGlvbnJlZmVyZW5jZSI6IjQyLTktODAxMDIiLCJsaXZlc3RhdHVzIjoiMCIsIm1lcmNoYW50bmFtZSI6IlRlc3QgVW5pdHRlc3QgU2l0ZSIsInNwbGl0ZmluYWxudW1iZXIiOiIxIiwieGlkIjoiYjI1YWJUUmxZVmxyV2tFMGJHWkZPVWh5YWpBPSIsImRjY2VuYWJsZWQiOiIwIiwic2V0dGxlZHVlZGF0ZSI6IjIwMTktMDYtMjYiLCJlcnJvcmNvZGUiOiIwIiwidGlkIjoiMjc4ODAwMDAiLCJpc3N1ZXIiOiJTZWN1cmVUcmFkaW5nIFRlc3QgSXNzdWVyMSIsIm1lcmNoYW50bnVtYmVyIjoiMDAwMDAwMDAiLCJtZXJjaGFudGNvdW50cnlpc28yYSI6IkdCIiwic3RhdHVzIjoiWSIsInRyYW5zYWN0aW9ucmVmZXJlbmNlIjoiNDItOS04MDEwMyIsInRocmVlZHZlcnNpb24iOiIxLjAuMiIsInBheW1lbnR0eXBlZGVzY3JpcHRpb24iOiJWSVNBIiwiYmFzZWFtb3VudCI6IjEwMDAiLCJlY2kiOiIwNSIsImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiY2F2diI6IkFBQUJBV0ZsbVFBQUFBQmpSV1daRUVGZ0Z6OD0iLCJhY3F1aXJlcnJlc3BvbnNlY29kZSI6IjAwIiwicmVxdWVzdHR5cGVkZXNjcmlwdGlvbiI6IkFVVEgiLCJzZWN1cml0eXJlc3BvbnNlc2VjdXJpdHljb2RlIjoiMiIsImN1cnJlbmN5aXNvM2EiOiJHQlAiLCJhdXRoY29kZSI6IlRFU1Q0NCIsImVycm9ybWVzc2FnZSI6Ik9rIiwiaXNzdWVyY291bnRyeWlzbzJhIjoiVVMiLCJtYXNrZWRwYW4iOiI0MTExMTEjIyMjIyMxMTExIiwic2VjdXJpdHlyZXNwb25zZXBvc3Rjb2RlIjoiMCIsImVucm9sbGVkIjoiWSIsInNlY3VyaXR5cmVzcG9uc2VhZGRyZXNzIjoiMCIsIm9wZXJhdG9ybmFtZSI6Im9wZXJhdG9yIiwic2V0dGxlc3RhdHVzIjoiMCJ9XSwic2VjcmFuZCI6IlBBR1BGeTU3TCJ9fQ.ybhLMCn-9ivxFd38zf3WhuXdn3c87Vj8PMgum7rBoUw"

If a JavaScript 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”.

Decoding the JWT

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

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

In its compact form, JWT consists of three parts separated by dots (“.”), in the following format:

Header.Payload.Signature

The header and payload are Base64Url encoded. You can decode these two values to retrieve the respective values. See below:

Decoded token

{"iat":1561549076,"payload":{"requestreference":"W42-4fq45cb0","version":"1.00","response":[{"transactionstartedtimestamp":"2019-06-26 11:37:56","parenttransactionreference":"42-9-80102","livestatus":"0","merchantname":"Test Unittest Site","splitfinalnumber":"1","xid":"b25abTRlYVlrWkE0bGZFOUhyajA=","dccenabled":"0","settleduedate":"2019-06-26","errorcode":"0","tid":"27880000","issuer":"SecureTrading Test Issuer1","merchantnumber":"00000000","merchantcountryiso2a":"GB","status":"Y","transactionreference":"42-9-80103","threedversion":"1.0.2","paymenttypedescription":"VISA","baseamount":"1000","eci":"05","accounttypedescription":"ECOM","cavv":"AAABAWFlmQAAAABjRWWZEEFgFz8=","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST44","errormessage":"Ok","issuercountryiso2a":"US","maskedpan":"411111######1111","securityresponsepostcode":"0","enrolled":"Y","securityresponseaddress":"0","operatorname":"operator","settlestatus":"0"}],"secrand":"PAGPFy57L"}}

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 the signature using the header and payload returned, by following the steps outlined on this page. The secret needed to re-calculate the signature is the same secret as shared with Support during setup, and then used when generating the JWT for the request.

Response fields

After you receive the response from “st.js”, 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.

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.
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).
10	Settlement in progress.
100	Instant settlement.
2	Payment authorised but suspended on Trust Payments’s 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 JavaScript.
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 JavaScript Library 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.	We strongly recommend against attempting further payments with this card, as the customer failed authentication, indicating an elevated risk of fraud. Instead, we recommend displaying an error message to the customer stating the payment was not completed, and offer alternative methods of payment.
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.

Your progress

You have now learned how to handle the response.