1. TRU Connect   
  2. JavaScript Library

1️⃣ Configure the library

​  Last updated: 

 

  Before proceeding, please ensure you have met all requirements
Click here to open this information in a new tab

 

Update your payment form

You will need to update your server-side payment form to include our “st.js” JavaScript Library (as shown in the example below). The JavaScript Library will process requests and handle the responses returned.

  Please ensure your system references the st.js library on the Trust Payments servers. This ensures your solution is always using the latest version of the library.

  When the customer enters their payment details into the payment form and submits, our st.js will contact the card issuer to determine if the card is enrolled. If the card issuer determines that there is an elevated risk of fraud, an overlay will automatically be displayed to the customer where they will be prompted for authentication.

To enable this behaviour, you will need to reference the JavaScript Library by including a defined configuration that uses a specific method (“st.Components”) within “st.js”.

Note: Ensure you include the anonymous function as shown in the example. This prevents the JS from being executed until the st.js has been loaded.

This basic example will render a simple checkout that prompts the customer for their card details, and processes a payment:

<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="<CDN_DOMAIN>"></script>
    <script>
      (function() {
        var st = SecureTrading({
          jwt : 'We explain how to construct this on the next page'
        });
        st.Components();
    })();
    </script>
  </body>
</html>

  The JavaScript Library is a managed service that is regularly updated to add new features and improve existing functionality. Because of this, the JavaScript Library must be retrieved for each payment request. Failure to do so may prevent your integration from working correctly and cause payment requests to fail.

Click here for a full list of domains and replace <CDN_DOMAIN> in the example above with the appropriate value for your integration.

  When using the Content Delivery Network (CDN) 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.

 

st-notification-frame Optional A <div> tag with attribute id=“st-notification-frame” can be included in the form to display invalid field and connection errors to the customer, so that they can resolve and retry the payment.

Note: If you are not using the Library to process the AUTH, we recommend that you do not include the st-notification-frame in your form, as this may cause conflicting confirmation messages to be displayed. e.g. The THREEDQUERY Authentication response may return success, but the subsequent authorisation may be declined.

Click here for further information on using the JavaScript Library to process the 3-D Secure authentication but not the AUTH.
st-form Required You must ensure that your payment form has been assigned the id “st-form” and an action attribute that contains a valid URL address hosted on your server. The address specified must be able to handle the data returned in application/x-www-form-urlencoded format (see the example below). Click here for an example.
Payment divs Required The following fields are required in the payment form:
  • “st-card-number” – The customer’s card number.
  • “st-expiration-date” – The card’s expiration date.
  • “st-security-code” – The card’s security code.

You must ensure that the card number, expiry date and security code DO NOT use an <input> tag, as doing so may lead to sensitive data being posted directly to your server.
st-animated-card Optional This is used to render a graphic of a card, which updates to show a preview of the customer’s card in real time as they type in their details.

 

Initialise the Library

You will need to update your server-side payment form to include our “st.js” JavaScript Library. The JavaScript Library will process requests and handle the responses returned. When the customer enters their payment details into your form and submits, our st.js will contact the card issuer to determine if the card is enrolled. If the card issuer determines that there is an elevated risk of fraud, an overlay will automatically be displayed to the customer where they will be prompted for  authentication.

To enable this behaviour, you will need to reference the JavaScript Library by including a defined configuration that uses a specific method (“st.Components”) within “st.js”.

Note: Ensure you include the anonymous function as shown in the example. This prevents the JS from being executed until the st.js has been loaded.

  By default, our 3-D Secure authentication targets the sandbox environment. To override this setting and instead target the production environment, you will need to ensure your payment form specifies
livestatus: 1.

(function() {
  var st = SecureTrading({ 
    jwt: 'INSERT YOUR JWT HERE',
    livestatus: 1
  }); 
  st.Components(); 
})();

  Once the st.js library has been initialised for card payments, the customer has up to 15 minutes to complete their payment session. If they fail to complete their session within this time, this will result in a missing token error.

 

Full library specification

  Field Description
table-optional.png animatedCard By setting this property to true, an animated graphic of a card will be rendered on the form based on where you have position the st-animated-card div (if this div is not present, the card will not be displayed). By default, the card will not be displayed (set to false).
table-optional.png buttonId

By default, the JavaScript will set the first button in the DOM to be the pay submit button. However, if you have multiple button tags on your payment form, the buttonId can be added to st.js configuration to target a specific button for submitting the request.

<html>
  <body>
    <form id="st-form"
    action="https://www.example.com"
    method="POST">
      <div class="example-form__section">
        <div class="example-form__group">
          <button type="submit"
          class="example-form__button"
          id="abcd">this is the pay button</button>
        </div>
      </div>
    </form>
    <script> 
      (function() {
        var st = SecureTrading({ 
          buttonId: 'abcd',
        }); 
      })();
    </script>
  </body>
</html>
table-optional.png componentIds

The default container IDs for st.Components are:

<div id="st-card-number"></div>
<div id="st-expiration-date"></div>
<div id="st-security-code"></div>
<div id="st-animated-card"></div>
<div id="st-notification-frame"></div>

It's possible to change the default ID for each component individually, for example:

componentIds: {
  animatedCard: "st-animate",
  cardNumber: "st-card",
  expirationDate: "st-expiry",
  notificationFrame: "st-notify",
  securityCode: "st-cvv"
}

Containers with custom IDs:

<div id="st-card"></div>
<div id="st-expiry"></div>
<div id="st-cvv"></div>
<div id="st-notify"></div>
<div id="st-animate"></div>
table-conditional.png disabledAutoPaymentStart

disabledAutoPaymentStart can be set with an array of payment method names.

The full list of supported names are:
["APPLEPAY", "CARD", "GOOGLEPAY"]

If the customer selects a payment method included in the array, the main payment process is postponed, allowing for additional checks and processes to be performed beforehand.

disabledAutoPaymentStart is used in conjunction with the library's paymentPreCheck event, which allows for the selected payment method to be determined and also provides a callback to start the payment once you have completed the additional steps.

The following is an example of how to prevent GOOGLEPAY transactions from being started immediately after the customer clicks the pay button, in order for additional validation to be performed. Once complete, you can notify the library to proceed with the payment by calling paymentStart();

<script>
(function() {
var st = SecureTrading({
  jwt,
  disabledAutoPaymentStart: ['GOOGLEPAY'],
});
st.Components();
st.GooglePay();
st.on('paymentPreCheck', (data) => {
  const {paymentMethod, paymentStart} = data;
  if (paymentMethod === 'GooglePay') {
    var validationPass = validateData();
    if (validationPass){
      paymentStart();
    } else {
      //Notify customer of issue
    }
  }
});
})();
</script>
  The main payment process will start automatically if the customer selects any payment method not listed in the disabledAutoPaymentStart array.
  Click here for further information about the paymentPreCheck event and other event options.
table-optional.png disableNotification By default, the JavaScript will display a success or error message on the checkout following a payment attempt. In cases where you are redirecting your customer to another page hosted on your website following a transaction, you may prefer to hide this message entirely for a more seamless checkout experience. To do so, you will need to include disableNotification with value true.

Note: If you have implemented a Digital Wallet solution (such as Apple Pay or Visa Checkout), please be aware this also hides any cancellation messages displayed by the JavaScript Library, in cases where the customer closes the wallet overlay prior to transaction completion.
table-optional.png errorReporting

By default, the ST.js has error reporting enabled, which allows us to monitor your JavaScript Library integration for errors that may impact the user payment experience during their checkout session. This is recommended and enabled by default. However, if you prefer to have error reporting disabled, you can do so by setting the property to false, for example:

errorReporting: false
table-conditional.png fieldsToSubmit

If a returning customer is paying with a saved card, where only the security code needs to be captured, you can configure the SecureTrading Config with:

fieldsToSubmit: ['securitycode']

This will ensure that only the security code input is rendered when invoking st.Components.

Please refer to this article to learn more about accepting payments with a saved card.
table-conditional.png formId

You can update the default "st-form" ID to what works best for your application. For example:

formId: 'my-checkout-form'
table-required.svg jwt

A signed JSON Web Token (JWT), generated on your server. To learn how to configure your JWT, please review this article
table-conditional.png livestatus This instructs whether the 3-D Secure checks are performed using the test environment or production environment. There are two possible values that can be submitted – 0 and 1 – and these are described as follows:
  • 0 – 3-D Secure checks are performed using the test environment (default behaviour when not included in your markup).
  • 1 – 3-D Secure checks are performed using the production environment (this is required when processing live payments, otherwise optional).
(function() {
  var st = SecureTrading({ 
    jwt: 'INSERT YOUR JWT HERE',
    livestatus: 0
  }); 
  st.Components(); 
})();
table-optional.png panIcon You can specify the card brand logo to be displayed in the card number field as the customer types into the payment form. To do so, you will need to update your server-side checkout form to include panIcon with value true.
table-optional.png placeholders

To update the placeholder text that will appear within the card payment input fields, you can use the placeholders config. Each placeholder can be updated individually. For example, if you’d prefer no placeholder in the card input, set it as an empty string:

placeholders : {
  'pan':'',
  'expirydate':'Expiry date',
  'securitycode':'Security code'
}
table-optional.png stopSubmitFormOnEnter

Submit this field with value true to prevent the customer from submitting the form by pressing the return key on their keyboard. Instead, they would click the pay submit button.

This may be required if your system relies on the customer clicking the pay submit button in order to perform updates on your server.
table-optional.png styles

You may style the st.Components inputs using styles. For a full range of styles options, you can reference the following article.

It's possible to change the default ID for each component. For example:

styles: {
 'background-color-input': '#e71b5a',
 'font-size-label': '18px',
 'color-input': '#fff'
}
table-optional.png submitCallback If you need to perform a callback after the payment session has ended, you can specify submitCallback. Here you would pass in a function to perform a sequence of actions. The customer’s browser will be returned an object called data, containing the result of the last gateway request. You should verify the response JWT before trusting the data returned.
table-optional.png submitFields When the customer attempts a payment, and the form is submitted to the URL specified in the action attribute, the following fields are included within a JWT:
  • baseamount
  • currencyiso3a
  • eci
  • enrolled
  • errorcode
  • errordata
  • errormessage
  • orderreference
  • settlestatus
  • status
  • transactionreference

However, if you prefer to specify your own list of fields to be posted, you can include the field submitFields in your form. For example:

submitFields: ['errorcode', 'transactionreference']

You can specify additional fields that lie outside of the list provided above. We document all supported fields on this page.
table-optional.png submitOnCancel

By default, if the customer cancels the transaction prior to completion, the customer will stay on the same page, allowing them to try again with a different payment method if preferred.

If you would rather the customer’s browser be redirected to the URL specified in the form action when the customer cancels, you can update the form to include submitOnCancel: true.

Note: Under this alternative configuration, no error message is displayed on the payment form prior to the browser redirect.
table-optional.png submitOnError By default, if an error occurs, the customer will stay on the same page, allowing them to attempt to correct the issue and try again. Any error messages will be displayed in the st-notification-frame div. (You do not need to modify the form, because submitOnError: false is submitted automatically)

If you would rather the customer’s browser be redirected to the URL specified in the form action when an error occurs, you can update the form to include submitOnError: true.

Note: Under this alternative configuration, no error message is displayed on the payment form prior to the browser redirect.
table-optional.png submitOnSuccess By default, the customer’s browser is redirected to the URL specified in the form action when a successful payment has completed. (submitOnSuccess: true is the default configuration)

Note: Under this default configuration, no success message is displayed on the payment form prior to the browser redirect.

If you would rather the customer’s browser to stay on the same page, showing a success message in the st-notification-frame div you can update the form to include submitOnSuccess: false.
table-optional.png translations

You can use the translations property to specify custom wording for text displayed on the st.Components validation and labels. You may also use it to update notification messages that are rendered in the notification container. 

translations:{
  'An error occurred': 'INSERT YOUR CUSTOM PHRASE HERE'
}

For a complete reference, please review this article.

  If you are receiving an error in your init response that is similar to the following:

{“ErrorNumber”:1010,”Message”:”Invalid Signature. Your request contains an invalid signature.”}

Please check your livestatus configuration is correct. i.e. If you are using a test site reference, ensure livestatus is submitted as 0 (or omit this field entirely) and if using a live site reference, ensure this is instead submitted as 1.

 

 

Your progress

The information above will enable you to start constructing your payment solution. Next, we recommend learning how to generate a JSON Web Token (JWT). These are used to verify that the data sent was not modified during the payment session.

Proceed to Step 2   

Was this article helpful?
0 out of 0 found this helpful
Avatar
Michael Buckley

 

Further reading on this topic

See more