Contents

Migrating from st.js version 1 to version 2

 

We have introduced a new version of the JavaScript Library, which we refer to as version 2. If you have already configured your solution to use version 1, this will continue to work and you do not need to make any immediate changes. However, you may not have access to all of the latest available features.

 

Why should you upgrade?

 


 

What functionality is available in version 2?

 

Tick

Version 2 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.)
External

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 2

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

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.

 

 

  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

 

Summary of changes from Version 1 to Version 2

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

 

Comparison of markup for Version 1 and Version 2


<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">
    <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/v2/st.js></script>
 <script> 
  (function() {
   var st = SecureTrading({  
    jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1In0sImlhdCI6MTU1OTAzMzg0OSwiaXNzIjoiand0LnVzZXIifQ.jXI151RhD5ob1qJkQOM9tk0wyyvlewGXsTTlkz-jiYA',          
    });  
   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 2 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">
  </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 2 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">
    <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 2 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">
    <button type="submit">Pay securely</button>
  </form>
</body>
</html>

 

Reference the new JavaScript Library

The version 2 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/v2/st.js"></script>
</body>
</html>

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

 


 

Handle other data

External
To use version 2, 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: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1In0sImlhdCI6MTU1OTAzMzg0OSwiaXNzIjoiand0LnVzZXIifQ.jXI151RhD5ob1qJkQOM9tk0wyyvlewGXsTTlkz-jiYA',          
      });  
    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 Secure Trading’s 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">
    <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">
    <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

External
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

 


 

Need assistance?

Life ring
If you have any questions regarding migration to version 2 of our JavaScript Library, click here for our contact details.