Contents

Library configuration

 

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.


<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" class="st-card-number"></div>
      <div id="st-expiration-date" class="st-expiration-date"></div>
      <div id="st-security-code" class="st-security-code"></div>
      <button type="submit" id="st-form__submit" class="st-form__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>

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

 

Specification

  Field Description
cancelCallback If you need to perform a callback after a payment has been cancelled (e.g. closing the Apple Pay payment sheet prior to completing the transaction), you can specify cancelCallback. Here you would pass in a function to perform a sequence of actions.
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/

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.

errorCallback If you need to perform a callback in the event an error occurs during the payment session, you can specify errorCallback. Here you would pass in a function to perform a sequence of actions.
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).

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

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”.
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.
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.

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.

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.

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.

successCallback If you need to perform a callback after a payment has been completed successfully, you can specify successCallback. Here you would pass in a function to perform a sequence of actions.

 

Info
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.