Process test payment
Once you have updated your payment form and configured the library, you can process a test card payment through our sandbox. Using the form you configured earlier, fill out the form with the following test payment credentials and click “Pay” to perform a test transaction.
When testing, you can use the following test card details to simulate a “Successful” response:
- Visa card ‘4111 1111 1111 1111’ or Mastercard ‘5100 0000 0000 0511’
- Set expiry date to any valid date in the future
- Use security code “123”
After the form has been submitted, the “st.js” will open the overlay in the browser for authentication. The results of the authentication performed and the subsequent payment will be added to the form (with id=“st-form”), which will then be posted directly to the server specified in the action attribute of the form, in the format of an application/x-www-form-urlencoded POST.
Decode JWT response
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:
'merchantname': 'Test merchant',
'transactionstartedtimestamp': '2020-11-19 14:13:36',
'acquirerresponsemessage': 'Approved or completed Successfully',
'merchantname': 'Test merchant',
'transactionstartedtimestamp': '2020-11-19 14:13:36'
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:
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)
After you receive the response, we recommend you review the information below when handling the customer’s payment session:
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.
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.
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.
You will need to check the errorcode returned to determine the outcome of the transaction:
|Error code||Description||Actions required|
|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.|
|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.|
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, if enabled).|
|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.|
The enrolled field will inform you if the customer’s card is enrolled in 3-D Secure:
|3-D enrolled||Description||Actions required|
|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.|
The status field will inform you if the customer was successfully authenticated during the 3-D Secure process:
|3-D status||Description||Actions required|
|N||The customer was not authenticated. The payment will not be processed.||
|R||Authentication was rejected. The payment will not be processed.|
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.
Now you have configured your library, you can begin to customise your solution further and enable additional features.
- Learn what happens after transactions have been processed.
- Update your solution to support Apple Pay.
- Securely store customer payment credentials for future transactions.
- Schedule automated subscription payments.
- Full list of features.