Contents

Payment form specification

You will need to update your server-side payment form to follow the structure shown in the mark-up below. Your server will need to generate the appropriate jwt value for each request. This form only includes the required fields. There are also optional fields that can be submitted – these are documented below.


<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/v2/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.

 

st-notification-frame

A <div> tag with attribute id=“st-notification-frame” is required, in order for invalid field and connection errors to be displayed to the customer, to inform them of the error so that they can resolve and retry the payment.


<html>
  <body>
    <div id="st-notification-frame"></div>
  </body>
</html>

 

st-form

You must ensure that your payment form has been assigned the id “st-form” and an action.

Ensure the action attribute 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).


<html>
  <body>
    <form id="st-form" action="https://www.example.com" method="POST">
    </form>
  </body>
</html>

Info
If you need to change the name of the identifier “st-form”, because your application doesn’t support the naming convention used (e.g. ASP.NET doesn’t support ids containing hyphens), click here for alternative mark-up that can be used.

 

Input fields

The following fields are required in the payment form:

Field Description
st-card-number The customer’s card number.
st-expiration-date The card’s expiration date.
st-security-code The card’s security code.
st-form__submit Button to submit the request.

 

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

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

 

st-animated-card

You must include the following mark-up in your form. 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.


<form id="st-form" action="https://www.example.com" method="POST">
  <div id="st-animated-card" class="st-animated-card-wrapper"></div>
</form>

 

Info
The card displayed to the customer is animated. When they click the security code field, the card will rotate to show the position of the security code (which can normally be found on the back of the card). For American Express cards, the card is not rotated, to show the security code is instead normally found on the front of the card.

 


 

JavaScript Library

You will need to update your server-side payment form to include our “st.js” JavaScript Library, by adding the following line:


<html>
  <body>
    <script src=<DOMAIN>/js/v2/st.js></script>
  </body>
</html>

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

 

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


<html>
  <body>
    <script>
      (function() {
        var st = SecureTrading({
          animatedCard: true <!-- If true, card is shown -->
        });
      })(); 
    </script>
  </body>
</html>

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

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

 


 

jwt

JSON Web Tokens are an open standard RFC 7519 method for securely transmitting data between two parties as a JSON object.


jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWNvZGUiOiJHQlAiLCJzaXRlcmVmZXJlbmNlIjoidGVzdF9zaXRlMTIzNDUifSwiaWF0IjoiMTU1OTAzMzg0OSIsImlzcyI6Imp3dC51c2VyIn0=.RI6FUGp4fehJyhxhy2hib2UO2pluqU4AXqz1l1lRJcY',

 


 

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:

 

The following example shows the form configured to process 3-D Secure checks using the production environment:


<html>
  <body>
    <script>
      (function() {
        var st = SecureTrading({  
          livestatus: 1,
        }); 
      })();
    </script>
  </body>
</html>

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

 


 

requestTypes (optional field)

We use the value of this field to determine the type of request(s) to be processed to our system.

If not submitted, we will process a standard 3-D Secure transaction (THREEDQUERY,AUTH).


<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/v2/st.js></script>
    <script> 
      (function() {
        var st = SecureTrading({  
          jwt: 'INSERT YOUR JWT HERE'
        });
        st.Components({"requestTypes":["ACCOUNTCHECK","THREEDQUERY","AUTH"]}); 
      })(); 
    </script>
  </body>
</html>



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

(The above would process ACCOUNTCHECK, THREEDQUERY and AUTH requests)

 

The following request types can be included in the list specified in this field. Click the links provided below to learn more about how these request types can be utilised within your integration, and the corresponding requirements your system will need to adhere to when doing so:

Important: Only certain combinations of request types is supported. Ensure you follow the specifications listed below.

 

Request types Description
THREEDQUERY For querying a card’s 3-D secure enrolment status. This is required for 3-D Secure to be processed.
AUTH Performs a payment, which debits funds from the customer’s account.
ACCOUNTCHECK Performs basic checks on the card and billing address details submitted.
Specification for use
SUBSCRIPTION Schedules an automated subscription in our subscription engine.
Specification for use
RISKDEC For processing requests to our Protect Plus system, for purposes of highlighting payments with suspicious characteristics.
Specification for use

 


 

buttonId (optional field)

If you have multiple button tags on your payment form, the buttonId can be added to ST() config to target a specific button for processing 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>

 

submitOnSuccess (optional field)

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, as shown in the example below:


<html>
  <body>
    <script> 
      (function() {
        var st = SecureTrading({  
          submitOnSuccess: false,    
        });  
      })();
    </script>
  </body>
</html>

In addition, you can use a callback function, if you need to update your server after the payment has completed, when setting submitOnSuccess: false. See below for an example:


function myCallback(data) {
 // Custom code to perform actions after payment completion
 // Data will contain the result of the last gateway request
 // You should verify the response JWT is genuine before trusting the data
};

var st = SecureTrading({
jwt:'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWNvZGUiOiJHQlAiLCJzaXRlcmVmZXJlbmNlIjoidGVzdF9zaXRlMTIzNDUifSwiaWF0IjoiMTU1OTAzMzg0OSIsImlzcyI6Imp3dC51c2VyIn0=.RI6FUGp4fehJyhxhy2hib2UO2pluqU4AXqz1l1lRJcY',
 submitCallback: myCallback
 });  

 

submitOnError (optional field)

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, as shown in the example below:

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


<html>
  <body>
    <script> 
      (function() {
        var st = SecureTrading({  
          submitOnError: false,    
        });  
      })();
    </script>
  </body>
</html>

 


 

panIcon (optional field)

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 be configured as follows:


<html>
  <body>
    <script>
      (function() {
        var st = SecureTrading({
          panIcon: true,   
        });
      })();
    </script>
  </body>
</html>

 

submitFields (optional field)

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:

 

However, if you prefer to specify your own list of fields to be posted, you can include the field submitFields in your form. The following is an example where only the fields errorcode and transactionreference will be included in the post:


<html>
  <body>
    <script> 
      (function() {
        var st = SecureTrading({  
        submitFields: ['errorcode', 'transactionreference'],
      });  
    })();
    </script>
  </body>
</html>

Info
You can specify additional fields that lie outside of the list provided above.

Click here for a list of supported fields

 


 

Disabling notifications

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 update your server-side checkout form to be configured as follows:


<html>
  <body>
    <script> 
      (function() {
        var st = SecureTrading({  
                jwt,
        disableNotification: true,
      });  
    })();
    </script>
  </body>
</html>

 


 

Posting optional fields

You can optionally include additional fields in the form and these will be posted to the URL specified in the action attribute. This includes hidden fields, which can be used to pass through additional data that isn’t shown to the customer on the page.


<input type="hidden" name="promotionCode" value="27"/>
<input type="text" name="DeliveryInstructions" value="leave in porch"/>

 

Tick
Your progress

You have now learned more about updating your payment form.