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">
    <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: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1In0sImlhdCI6MTU1OTAzMzg0OSwiaXNzIjoiand0LnVzZXIifQ.jXI151RhD5ob1qJkQOM9tk0wyyvlewGXsTTlkz-jiYA',          
    });  
   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.


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

 


 

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


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

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">
.
.
<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">
.
.
<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:


<script src="<DOMAIN>/js/v2/st.js"></script>

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


<script src="<DOMAIN>/js/v2/st.js"></script>
<script>
 (function() {
  var st = SecureTrading({
jwt:'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWNvZGUiOiJHQlAiLCJzaXRlcmVmZXJlbmNlIjoidGVzdF9zaXRlMTIzNDUifSwiaWF0IjoiMTU1OTAzMzg0OSIsImlzcyI6Imp3dC51c2VyIn0=.RI6FUGp4fehJyhxhy2hib2UO2pluqU4AXqz1l1lRJcY',
animatedCard: true <!-- If true, card is shown -->
   });  
  st.Components(); 
 })(); 
</script>

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:


   var st = SecureTrading({  
    jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7ImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYmFzZWFtb3VudCI6IjEwNTAiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwic2l0ZXJlZmVyZW5jZSI6InRlc3Rfc2l0ZTEyMzQ1In0sImlhdCI6MTU1OTAzMzg0OSwiaXNzIjoiand0LnVzZXIifQ.jXI151RhD5ob1qJkQOM9tk0wyyvlewGXsTTlkz-jiYA',
    livestatus: 1
    });  

 


 

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)

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 highlighted in bold in the example below:


submitOnSuccess: false,

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 highlighted in bold in the example below:


submitOnError: true,

 


 

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:


submitFields: ['errorcode', 'transactionreference']

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

Click here for a list of supported fields

 


 

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.