Migrating st.js from version 1 to version 3

We have introduced a new version of the JavaScript Library, which we refer to as st.js v3.

The v1 library will be sunset as of 1st December 2021.

 

Why should you upgrade from version 1?

  • EMV 3DS (3-D Secure version 2) support  - All businesses within the EEA (European Economic Area) are mandated to use 3-D Secure version 2 when processing e-commerce transactions, as part of the PSD2 mandate. 
  • By utilising the default payment form rendered by the v3 library, your system no longer has access to sensitive payment data from within your own JavaScript, resulting in less stringent self-assessment criteria for PCI DSS.
  • Increased security.

 

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 EMV 3DS.
  • Processing payments with supported digital wallets:
    • Apple Pay
    • Google Pay
  • Scheduling a subscription following EMV 3DS-authenticated payments.
  • Accompanying the payment with other secondary requests (e.g. Account Checks).

  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
  • Supported 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?

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

 

  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.
  • 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. Any unauthorised changed to the JWT will invalidate the signature and the request will be rejected by Trust Payments.

  Summary of changes from Version 1 to Version 3 (Apple Pay)

The changes needed to upgrade your solution from version 1 to version 3 of the JavaScript Library can be summarised as follows:

  • New <div> for handling messages to the customer (i.e. error and success messages).
  • New form id for the payment form.
  • New <div> tag to indicate where the Apple Pay button should be rendered
  • 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. Any unauthorised changed to the JWT will invalidate the signature and the request will be rejected by Trust Payments.
  • With the introduction of JSON Web Tokens, Apple Pay no longer requires a site security hash to be provided.

 

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 following methods:

  • st.Components() - Render the card payment form.
  • st.ApplePay() - Render the Apple Pay button.

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 or Apple Pay payment.

To assist with your migration of card and Apple Pay solutions, 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 the following articles:

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>
<div class="st-applepay-button"></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"
});
new SecureTrading.ApplePay({
sitereference: "test_site12345",
paymentRequest:{
"total":{
"label":"Pay now",
"amount":"2.00"
},
"countryCode":"GB",
"currencyCode":"GBP",
"merchantCapabilities":["supports3DS", "supportsCredit", "supportsDebit"],
requiredBillingContactFields: ["postalAddress"],
requiredShippingContactFields: ["postalAddress", "name", "phone", "email"],
supportedNetworks:["visa", "masterCard"]
},
"merchantId":"your.merchant.id",
"sitesecurity":"gABC123DEFABC"
});
</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.

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 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 <DOMAIN> with a supported domain. Click here for a full list.

 

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

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