Library configuration

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

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

 

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-conditional.png datacenterurl If you intend on processing requests through our US platform, you will need to override the datacenterurl to point to the US JWT endpoint (defaults to EU platform),  by including the following URL:

https://webservices.securetrading.us/jwt/

Required on US platform - otherwise optional.

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-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 environmen(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 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 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.

  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.

Click here to continue.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request