API Configuration


Process overview

  1. When the customer presses the Visa Checkout button, they will be presented with the Visa Checkout Payment Widget.
  2. When the customer agrees to the payment, an AUTH request is submitted to Trust Payments.
  3. Trust Payments contacts the acquiring bank to request authorisation for the transaction.







It is recommended that your customers use one of the following browsers to have the best experience while using Visa Checkout:

  • Internet Explorer 11
  • Firefox (current version through 10 versions prior)
  • Chrome (current version through 10 versions prior)
  • Safari 6 or later
  • Android 5 or later



Update your server-side payment form

You will need to update your server-side payment form as follows:


Visa Checkout button
Visa Checkout button


Visa Checkout library

When the customer presses the Visa Checkout button, our st.js contacts Visa to initiate the payment session and display the Visa Checkout Payment Widget. To enable this behaviour, you will need to reference the Visa Checkout library by including additional markup on your payment form, as shown in the tabs below. This markup consists of fields and values that follow Visa’s own specification.

First of all, you will need to add a div placeholder into the payment form, like so:

<div class="st-wallet-button"></div>


Then you will need to update your Javascript to also call our Visa Checkout library. You can use the below as a guide to help you configure the button to meet the needs of your own checkout. Below this example, we provide information on values that can be submitted in these fields.

    <div id="st-notification-frame"></div>
        <form id="st-form" action="" 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
        <div class="st-wallet-button"></div>
     <div id="st-visa-checkout"></div>
    <script src=<DOMAIN>/js/v2/st.js></script>
          buttonSettings: {
            size: '154',
            color: 'neutral'
          livestatus: 0,
          merchantId: 'SDUT1MEXJO10RARJF2S521ImTyKfn3_JmxePdXcydQIUb4kx4',
          paymentRequest: {
            "currencyCode": "GBP",
            "subtotal": "10.99",
            "total": "10.99",
          placement: 'st-visa-checkout',
          settings: {
            displayName: 'My Test Site'

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


Required fields

The following fields are all required when calling the Visa Checkout library:

Field name Type Length Description
livestatus Numeric 1 Submit 0 to process transactions via Visa’s sandbox.

Submit 1 when processing live transactions.

Important: You must ensure you submit 1 when processing live transactions, otherwise payments will still be processed through Visa’s sandbox.

merchantId Alphanumeric including symbols 26 You will need to specify your Visa Checkout merchant id.

Visa refer to this field as the API key in their specification.

paymentRequest Object N/A Payment request information from the Visa Checkout library initialisation.
paymentRequest / currencyCode Alpha 3 The transaction currency code in ISO3a format.
paymentRequest / subtotal Numeric Max 9 digits before an
optional decimal point and 4 decimal digits
The transaction amount before applying discounts.
paymentRequest / total Numeric Max 9 digits before an
optional decimal point and 4 decimal digits
Full transaction amount after applying discounts.
Alphanumeric N/A This must be the name of the Visa Checkout button div id. It is used to render the payment button on the checkout.

For a full specification of Visa’s fields, please refer to their documentation.


The customer presses the Visa Checkout button on your checkout page.

Our JavaScript submits a request to initialise a new Visa Checkout session, and if successful, the customer’s device displays the Visa Checkout Payment Widget.



Understanding the Visa Checkout Payment Widget

When the customer presses the Visa Checkout button, the Visa Checkout Payment Widget is displayed. This is a secure interface hosted by Visa that allows existing customers to sign in, choose their preferred payment card and delivery address (if applicable), and agree to the transaction. Alternatively, users who have not yet signed up to use Visa Checkout can register without leaving your hosted checkout page, and complete the payment once they are ready. Once the payment has been completed, the st.js embedded on your checkout ensures the customer is seamlessly redirected back to your checkout to allow for a success message to be displayed. Click here to learn more.



Processing the authorisation

Status good
By default, the “st.js” JavaScript will send a request to our listener, which will then submit an AUTH request automatically.



Payment completion

After the customer has submitted the form to the “st.js”, authentication will be performed, followed by the payment. If the payment is successful, the Payment Widget will close to indicate the payment is complete. The response will be posted directly to your webserver in the form of a new JWT (click here for further info). The customer’s browser will be redirected to the URL specified in the form action attribute.

(If an error occurs during the payment, the Payment Widget will close and the customer will remain on the checkout)



As with regular card payments, records of all AUTH transactions processed using Visa Checkout can be viewed in MyST. When viewing Visa Checkout transactions in MyST, the “Wallet source” and “Token source type” fields will be displayed as “VISACHECKOUT”. Click here to view our MyST documentation.




Your test site reference will connect to the Visa Checkout testing sandbox. Therefore, in order to process payments on your test site reference, you will need to add test card details to the Visa Checkout wallet. Click here for our testing documentation.

Before you start processing payments on your production site reference, you must ensure the livestatus value submitted in your payment form is changed from “0” to “1”, otherwise payments will continue to be processed to Visa’s sandbox environment.