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:
- 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.
- 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.
<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>
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-apple-pay"></div>
</form>
<script src="<CDN_DOMAIN>"></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
submitOnSuccess:true,
submitOnError:false,
submitOnCancel:false, <!--Set true if you want to redirect on ApplePay wallet screen cancellations (3DS ACS cancel is N/A)-->
submitCallback: myCallback,
livestatus: 0 or 1 <!--defaults to 0 (testing) and should be set to 1 when live(production)-->
});
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'pay',
merchantId: 'your.merchant.id',
paymentRequest: {
countryCode: 'GB',
currencyCode: 'GBP',
merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
supportedNetworks: ["visa","masterCard"],
requiredBillingContactFields: ["postalAddress"],
requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
total: {
label: 'Trust Payments Merchant',
amount: '10.00'
}
},
buttonPlacement: 'st-apple-pay'
});
function myCallback(data) { <!--Perform task once payment request is completed -->};
})();
</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.
<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" method="POST">
</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:
<html>
<body>
<script src="https://webservices.securetrading.net/js/st.js"></script>
</body>
</html>
<html>
<body>
<script src="<CDN_DOMAIN>"></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/127.0.0.1 environment. To test your application locally with CDN, you will need to run your test application with your IPv4 address rather than localhost. After performing a lookup of your IPv4 address, you will need to replace localhost in your browser with the IP address retrieved.
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.
<html>
<body>
<script>
new SecureTrading.ApplePay({
<APPLE CONFIG>
});
</script>
</body>
</html>
<html>
<body>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE'
});
st.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.
<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>
<html>
<head>
</head>
<body>
<div id="st-notification-frame"></div>
<form id="st-form" action="https://www.example.com" method="POST">
<div id="st-apple-pay"></div>
</form>
<script src="<CDN_DOMAIN>"></script>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE',
submitOnSuccess:true,
submitOnError:false,
submitOnCancel:false, <!--Set true if you want to redirect on ApplePay wallet screen cancellations (3DS ACS cancel is N/A)-->
submitCallback: myCallback,
livestatus: 0 or 1 <!--defaults to 0 (testing) and should be set to 1 when live(production)-->
});
st.ApplePay({
buttonStyle: 'white-outline',
buttonText: 'pay',
merchantId: 'your.merchant.id',
paymentRequest: {
countryCode: 'GB',
currencyCode: 'GBP',
merchantCapabilities: ['supports3DS', 'supportsCredit', 'supportsDebit'],
supportedNetworks: ["visa","masterCard"],
requiredBillingContactFields: ["postalAddress"],
requiredShippingContactFields: ["postalAddress","name", "phone", "email"],
total: {
label: 'Trust Payments Merchant',
amount: '10.00'
}
},
buttonPlacement: 'st-apple-pay',
merchantUrl:'<payment URL endpoint>'
});
function myCallback(data) { <!--Perform task once payment request is completed -->};
})();
</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.
<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" method="POST">
</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:
<html>
<body>
<script src="https://webservices.securetrading.net/js/st.js"></script>
</body>
</html>
<html>
<body>
<script src="<CDN_DOMAIN>"></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:
<html>
<body>
<script>
new SecureTrading.ApplePay({
<APPLE CONFIG>
});
</script>
</body>
</html>
<html>
<body>
<script>
(function() {
var st = SecureTrading({
jwt: 'INSERT YOUR JWT HERE'
});
st.ApplePay({
<APPLE CONFIG>
});
})();
</script>
</body>
</html>