We have introduced a new version of the JavaScript Library, which we refer to as st.js v3.
Process overview of Version 3
What will the customer see during the payment?
- The customer agrees to a payment on your checkout.
- If enrolled in 3-D Secure, the customer’s browser will display an overlay, where they may be asked to complete some basic actions to authenticate their identity.
Additional data regarding the payment session and the customer’s device is shared with the card issuer, allowing for risk-based decisions without always needing to seek additional forms of authentication from the customer. As such, the customer may not be required to perform authentication. In this case, the overlay may not be displayed and the authorisation would be processed without interaction.
The following is an example of an overlay the customer may be displayed for authentication prior to completing a payment. The appearance of the overlay and the nature of authentication required is determined by the customer’s card issuer. For example:
- Enter a code sent to a mobile number via SMS.
- Biometric security, such as fingerprint / facial / voice recognition.
- Enter a PIN or password.
- Following any checks and authentication required by the customer’s card issuer, the overlay will close automatically, and the payment will be processed. Following this, the checkout will display a success message to the customer.
If the authentication fails, your checkout will display an error message and provide the customer an opportunity to attempt a new payment with a different card.
Behind-the-scenes
Summary of development changes needed
The changes needed to upgrade your solution from version 1 to version 3 of the JavaScript Library can be summarised as follows:
- Your system no longer needs to submit payment requests including the cachetoken using our Webservices API.
- You will need to contact our Support Team to create a new user with the role “Webservices JWT”.
- New <div> for handling response messages (i.e. success and decline messages).
- New form id for the payment form.
- New <div> tags for inputting card details on the form.
- New mark-up for the submit button on the form.
- Change the URL path so the new library is referenced from our CDN
- Payment data is included within a signed JWT (JSON Web Token) generated by our merchants on their server side using a shared secret provided by Trust Payments. Any unauthorised changes to the JWT will invalidate the signature and the request will be rejected by Trust Payments.
Comparison of mark-up for Version 1 and Version 3
Creating a single instance of the st.js v3 will enable you to call the method st.Components(), which is used to render the card payment form.
Configuring the 'st' instance will impact the flow of each payment method. For example, by setting submitOnSuccess to be true, this will redirect the customer to the form action url following the completion of any successful card payment.
To assist with your migration of card solution, please review the examples below.
For a more in-depth guide of all configuration options our st.js v3 library has to offer, please refer to this article.
<html>
<head>
<style>
#st-payment input.st-error {
background-color: #ffc6c7;
border: 2px solid #ffb5b5;
}
#st-message .st-error {
background: #ffcdcd;
border: 2px solid #ffb5b5;
padding: 4px 4px 4px 28px !important;
}
</style>
</head>
<body>
<div id="st-message"></div>
<form id="st-payment" action="https://www.example.com">
Pan:
<input type="text" data-st-field="pan" autocomplete="off" /></br>
Expiry Month:
<input type="text" data-st-field="expirymonth" autocomplete="off" /></br>
Expiry Year:
<input type="text" data-st-field="expiryyear" autocomplete="off" /></br>
Security Code:
<input type="text" data-st-field="securitycode" autocomplete="off" /></br>
<input type="submit" name="mybtn" />
</form>
<script src="https://webservices.securetrading.net/js/st.js"></script>
<script>
new SecureTrading.Standard({
sitereference: "test_site12345", locale: "en_gb"
});
</script>
</body>
</html>
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number"></div>
<div id="st-expiration-date"></div>
<div id="st-security-code"></div>
<button type="submit">Pay securely</button>
</form>
<script src="https://cdn.eu.trustpayments.com/js/latest/st.js"></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
submitOnSuccess:true,
submitOnError:false,
submitCallback: myCallback,
livestatus: 0 or 1 <!--defaults to 0 (testing) and should be set to 1 when live(production)-->
});
st.Components();
function myCallback(data) { <!--Perform task once payment request is completed -->};
})();
</script>
</body>
</html>
Handle messages to the customer
There is a new <div> for handling messages to the customer (i.e. error and success messages). You will need to substitute the old mark-up shown below for the new mark-up in the version 3 tab.
<html>
<body>
<div id="st-message"></div>
</body>
</html>
<html>
<body>
<div id="st-notification-frame"></div>
</body>
</html>
Reference new form id
You will need to replace the old form id “st-payment” with “st-form”, as shown below.
<html>
<body>
<form id="st-payment" action="https://www.example.com">
</form>
</body>
</html>
<html>
<body>
<form id="st-form" action="https://www.example.com" method="POST">
</form>
</body>
</html>
Input card details securely
The <input> tags in the form have been replaced with <div> tags with different ids for each card details field. Your server renders the payment form containing unique <div> tags, each of which contains an iframe hosted by the Trust Payments servers which contains a different card input field. You will need to substitute the old mark-up shown below for the new mark-up in the version 3 tab.
<html>
<body>
<form id="st-payment" action="https://www.example.com">
Pan:
<input type="text" data-st-field="pan" autocomplete="off" /></br>
Expiry Month:
<input type="text" data-st-field="expirymonth" autocomplete="off" /></br>
Expiry Year:
<input type="text" data-st-field="expiryyear" autocomplete="off" /></br>
Security Code:
<input type="text" data-st-field="securitycode" autocomplete="off" /></br>
</form>
</body>
</html>
<html>
<body>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-card-number"></div>
<div id="st-expiration-date"></div>
<div id="st-security-code"></div>
</form>
</body>
</html>
Pay button
The Pay button is now rendered from a <button> tag (rather than an <input> tag). You will need to substitute the old mark-up shown below for the new mark-up in the version 3 tab.
<html>
<body>
<form id="st-payment" action="https://www.example.com">
<input type="submit" name="mybtn" />
</form>
</body>
</html>
<html>
<body>
<form id="st-form" action="https://www.example.com" method="POST">
<button type="submit">Pay securely</button>
</form>
</body>
</html>
Reference the new JavaScript Library
The version 3 library has a new URL to reference. The URL depends on the platform you are processing requests on:
<html>
<body>
<script src="https://webservices.securetrading.net/js/st.js"></script>
</body>
</html>
<html>
<body>
<script src="https://cdn.eu.trustpayments.com/js/latest/st.js"></script>
</body>
</html>
When moving to using the Content Delivery Network (CDN) instead of webservices to reference the st.js library, be aware that the CDN will block requests from your localhost/127.0.0.1 environment. To test your application locally with CDN, you will need to run your test application with your IPv4 address rather than localhost. After performing a lookup of your IPv4 address, you will need to replace localhost in your browser with the IP address retrieved.
Handle other data
To use version 3, you will need to submit certain data in a JWT (JSON Web Token).
Data included within the JWT are prevented from modification by unauthorised third parties.
Click here to learn how to generate the JWT.
Here is an example of a code snippet that includes a JWT:
<html>
<body>
<script>
new SecureTrading.Standard({
sitereference: "test_site12345", locale: "en_gb"
});
</script>
</body>
</html>
<html>
<body>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE'
});
st.Components();
})();
</script>
</body>
</html>
Optionally, data that is expected to be modified by the customer on your checkout, following the form being rendered in their browser (e.g. their billing names), can be included in the mark-up using <input> tags as shown in the example below.
Important: To ensure these fields are posted securely to the Trust Payments servers, you must include the attribute data-st-name with the field name the data maps to on our system. You can find information on fields that can be submitted when processing payments on this page.
<html>
<body>
<form id="st-form" action="https://www.example.com" method="POST">
<input type="text" name="title" data-st-field="billingprefixname">Mr</input>
<input type="text" name="forename" data-st-field="billingfirstname">Joe</input>
<input type="text" name="surname" data-st-field="billinglastname">Bloggs</input>
</body>
</html>
<html>
<body>
<form id="st-form" action="https://www.example.com" method="POST">
<input type="text" name="title" data-st-name="billingprefixname">Mr</input>
<input type="text" name="forename" data-st-name="billingfirstname">Joe</input>
<input type="text" name="surname" data-st-name="billinglastname">Bloggs</input>
</body>
</html>
Test your solution
It is imperative that you test these changes using a test site reference before processing live payments.
Click here for payment credentials you can use to simulate different responses from our system.
