Migrating st.js from version 1 to version 3 for Apple Pay

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

 

Process overview of Version 3

This article will provide instructions for migrating your JavaScript version 1 Apple Pay integration to one of our supported flows for version 3. There are two flows:

  1. Default flow - The library captures the wallet token and submits for authorisation to the TRU Connect platform. Click here to go to the relevant section.
  2. Alternative flow - For merchants who would rather receive the Apple wallettoken data and send an API request to process the AUTH themselves, the property merchantUrl should be set in the st.js st.ApplePay method config. Click here to go to the relevant section.

 

Default flow migration

  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

The following documentation is a summary of the changes when migrating your Apple Pay configuration from JavaScript Library version 1 to version 3, and you can follow this for a basic introduction.

  Alternatively, click here for full documentation of the version 3 solution.

Creating a single instance of the st.js v3 will enable you to call the method st.ApplePay(), which is used to render the Apple Pay button and present the payment sheet.

st.js v1 st.js v3
<html>
<head>
</head>
<body>
<div id="st-message"></div>
<form id="st-payment" action="https://www.example.com">
<div class="st-applepay-button"></div>
</form>
<script src="https://webservices.securetrading.net/js/st.js"></script>
<script>
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>

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>

 

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.

 

Creating and configuring an instance of the library

  When using JavaScript Library version 3, you will be expected to provide a JWT (JSON Web Token) to the instance of the library. The JWT payload will contain the required fields needed to process payments.
Data included within the JWT are protected from modification by unauthorised third parties.
Click here to learn how to generate the JWT.

Having created an instance of the JavaScript Library, you can call an ApplePay method, which requires you to pass in a configuration to set up the payment button and payment sheet.

Here is an example of a code snippet that includes a JWT in the instance configuration and invoking the ApplePay payment method.

st.js v1 st.js v3
<html>
<body>
<script>
new SecureTrading.ApplePay({
<APPLE CONFIG>
});
</script>
</body>
</html>

 

Alternative flow migration

  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.
  • The alternative flow requires a merchantUrl be specified in the st.ApplePay() configuration.

 

Comparison of mark-up for Version 1 and Version 3

The following documentation is a summary of the changes when migrating your Apple Pay configuration from JavaScript Library version 1 to version 3, and you can follow this for a basic introduction.

  Alternatively, click here for full documentation of the version 3 solution.

Creating a single instance of the st.js v3 will enable you to call the method st.ApplePay(), which is used to render the Apple Pay button.

st.js v1 st.js v3
<html>
<head>
</head>
<body>
<div id="st-message"></div>
<form id="st-payment" action="https://www.example.com">
<div class="st-applepay-button"></div>
</form>
<script src="https://webservices.securetrading.net/js/st.js"></script>
<script>
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",
"merchantUrl":"<payment URL endpoint>"
});
</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>

 

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.

 

Creating and configuring an instance of the library

  When using JavaScript Library version 3, you will be expected to provide a JWT (JSON Web Token) to the instance of the library. The JWT payload will contain the required fields needed to process payments.
Data included within the JWT are protected 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.ApplePay({
<APPLE CONFIG>
});
</script>
</body>
</html>
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request