Migrating st.js from version 1 to version 3 for card transactions

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?

  1. The customer agrees to a payment on your checkout.
  2. 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.

ppg-journey-acs.png

  1. 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

stjsv3-flow-1304.svg

 

  Summary of changes from Version 1 to Version 3 (Card payments)

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 perform the following steps:
    • Create a new user with the role “Webservices JWT”.
    • If you are not already processing 3-D Secure version 1 transactions with Trust Payments, you will need to ask our Support Team to add the necessary 3-D Secure version 2 provider details on your test and live site references.
    • Alternatively, if you are already processing 3-D Secure version 1 transactions with Trust Payments, using your test and live site references: To ensure your existing solution continues to function, we recommend registering new site references with the necessary credentials to process transactions with 3-D Secure version 2 (in addition to your existing site references).
  • Your system no longer needs to redirect the customer’s browser to the ACS server for authentication.
  • (By default the v3 st.js is configured to handle the above steps 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 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 changed 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.

st.js v1 st.js v3
<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>

Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.

 

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.

st.js v1 st.js v3
<html>
<body>
<div id="st-message"></div>
</body>
</html>

 

Reference new form id

You will need to replace the old form id “st-payment” with “st-form”, as shown below.

st.js v1 st.js v3
<html>
<body>
<form id="st-payment" action="https://www.example.com">
</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.

st.js v1 st.js v3
<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>

 

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.

st.js v1 st.js v3
<html>
<body>
<form id="st-payment" action="https://www.example.com">
<input type="submit" name="mybtn" />
</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:

st.js v1 st.js v3
<html>
<body>
<script src="https://webservices.securetrading.net/js/st.js"></script>
</body>
</html>

Replace <CDN_DOMAIN> with a supported domain. Click here for a full list.

  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 environment. To test it locally, you will need to run your test application via IP rather than localhost.

 

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:

st.js v1 st.js v3
<html>
<body>
<script>
new SecureTrading.Standard({
sitereference: "test_site12345", locale: "en_gb"
});
</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.

st.js v1 st.js v3
<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>

 

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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request