Migrating st.js from version 1 to version 3
Why should you upgrade from version 1?
-
Version 3 supports JSON Web Tokens (JWT), which are utilised to further protect data from unauthorised modification during the payment process.
- It also supports seamless integration of 3-D Secure v2, by utilising our API to perform the THREEDQUERY request and authenticate the customer as part of the payment process.
- The library automatically performs the payment once the customer has been sufficiently authenticated, meaning you no longer need to implement server-to-server calls in your own checkout.
- The new solution allows you to easily append additional input fields to your form using standard <input> tags, and these are included in all requests posted to our gateway.
- Because your system no longer has access to sensitive payment data from within your own JavaScript, the PCI DSS requirement is lower, resulting in less stringent self-assessment criteria.
What functionality is available in version 3?
Version 3 at its core is designed for performing Customer-Initiated Transactions (CIT) that are authenticated using Strong Customer Authentication (SCA).
This includes:
- Processing payments with 3-D Secure v2
- Processing payments with a supported digital wallet (e.g. Apple Pay)
- Scheduling a subscription following a 3-D Secure v2 payment
- Accompanying the payment with other secondary requests (e.g. Account checks, Protect Plus, etc.)
Other functions are performed using our Webservices API.
This includes:
- Merchant-Initiated Transactions (MIT) / Customer Not Present (CNP) transactions
- Re-authorisations
- Refunds and payouts
- Payments not using Strong Customer Authentication (SCA)
- Transactions queries and updates
- Certain Alternative Payment Methods (APM) (e.g. PayPal, Alipay & WeChat Pay)
- Incremental authorisations
Click here to open our Webservices API documentation in a new tab
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.
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:
a. Enter a code sent to a mobile number via SMS.
b. Biometric security, such as fingerprint / facial / voice recognition.
c. 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 changes from Version 1 to Version 3
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.
- Your system no longer needs to redirect the customer’s browser to the ACS server for authentication.
- (The new JavaScript Library can be configured to handle the above automatically)
- New <div> for handling messages to the customer (i.e. error and success messages).
- New form id for the payment form.
- New <div> tags for inputting card details on the form.
- New markup for the submit button on the form.
- Change the URL path so the new library is referenced.
- Data and components are submitted in a new way. Data is included within a JWT (JSON Web Token), which is used to prevent data from being modified by unauthorised parties during the transaction.
Comparison of markup for Version 1 and Version 3
<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="<DOMAIN>/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=<DOMAIN>/js/v3/st.js></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE'
});
st.Components();
})();
</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 markup shown below for the new markup 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 field. You will need to substitute the old markup shown below for the new markup 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 markup shown below for the new markup 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="<DOMAIN>/js/st.js"></script> </body> </html>
<html> <body> <script src="<DOMAIN>/js/v3/st.js"></script> </body> </html>
Replace <DOMAIN> with a supported domain. Click here for a full list.
Handle other data
Data included within the JWT are prevented from modification by unauthorised third parties.
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 delivery address), 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
Click here for payment credentials you can use to simulate different responses from our system
Need assistance?
