Contents

Migrating st.js from version 2 to version 3

 

What has changed in version 3 and why?

Version 3 is an update to our JavaScript Library that requires minimal development work to implement. The main purpose of the update is to improve the handling of data in requests to Trust Payments, by ensuring the payment field data submitted to the gateway is defined within the JWT payload.

 


 

What is happening to version 2?

We will continue to support version 2 of our JavaScript Library, however we strongly recommend upgrading your solution to version 3 as soon as possible.

If you do not migrate to version 3, your existing solutions will continue to function as normal. You will be notified when we begin to phase out older versions of our libraries in 2021.

 


 

Configuration

 

Change end-point URL

The script referenced in your payment form needs to be changed to:

<DOMAIN>/js/v3/st.js


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

 

Specify request types in the JWT payload

When using version 3, it is mandatory to specify the types of request to be processed in every request to Trust Payments. This is now done in the JWT payload, rather than within st.Components method.

 

3-D Secure authenticated payments

Under version 2, the JS Library would always process THREEDQUERY and AUTH requests automatically (for 3-D Secure authentication and then seeking authorisation for payment, respectively). To replicate this behaviour under version 3, the list requesttypedescriptions must be included in the JWT payload, with value [“THREEDQUERY”,”AUTH”].

 

Form example:


<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/v2/st.js></script>
 <script> 
  (function() {
   var st = SecureTrading({  
    jwt: 'INSERT YOUR JWT HERE'
    });  
   st.Components(); 
  })(); 
 </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>

Payload example:


{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345"},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}

 

Other request type combinations

If you are already specifying custom request type combinations, this needs to be removed from the st.Components method and instead included in the list requesttypedescriptions must be included in the JWT payload. The following example shows how to migrate an ACCOUNTCHECK, THREEDQUERY, AUTH request sequence:

 

Form example:


<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/v2/st.js></script>
 <script> 
  (function() {
   var st = SecureTrading({  
    jwt: 'INSERT YOUR JWT HERE'
    });  
   st.Components({"requestTypes":["ACCOUNTCHECK","THREEDQUERY","AUTH"]}); 
  })(); 
 </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>

Payload example:


{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345"},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["ACCOUNTCHECK","THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}

 

Bypassing 3-D Secure for specified payment types

If you are specifying payment methods to not be subject to 3-D Secure authentication, you will need to removeĀ bypassCards from the ST configuration. Instead, the field threedbypasspaymenttypes needs to be referenced in the JWT payload.

 

Warning
In order for your solution to be compliant with the Revised Directive on Payment Services (PSD2), you must ensure all transactions are performed using 3-D Secure.

 

Form example:


<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/v2/st.js></script>
 <script> 
  (function() {
   var st = SecureTrading({  
    jwt: 'INSERT YOUR JWT HERE',
    bypassCards: ['DISCOVER']
    });  
   st.Components(); 
  })(); 
 </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>

Payload example:


{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345"},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","threedbypasspaymenttypes":["DISCOVER"],"requesttypedescriptions":["THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}

 

Need assistance?

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