Deprecation planned

Please use the new Volt Embedded Checkout. It is faster, slicker and a lot more!

Integration guide 

Integration of our embedded checkout v1 can be achieved in just three steps.

  1. Creating a payment (server-side)
  2. Passing the payment information to your application (client-side)
  3. Initialising and configuring Drop-in component (client-side)

Request a payment (server-side)


Please ensure you’ve authenticated and have an access token to continue.  The API authentication process is explained here.


Payments can be requested from either the Sandbox or Production environment. We recommend starting with Sandbox, where you can choose one of the model banks and test the end-to-end process without making real payments.


  • Sandbox
  • Production

Request headers

Supply an Authorization header containing your access token, and an appropriate content-type.

Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6Ijc2MGEwNDRkMDkwZmUxNmE0YzRkMWRjMWE5NDU1MTgxMzgxZDRkNDIyZGUyNDY5NjQ0NDI4NWNkZjk1NWJkMzBjMjcxYzYxNjE0MzkyMmI0In0
Content-type: application/json

Request body

  "currencyCode": "GBP",
  "amount": 12345,
  "type": "OTHER",
  "uniqueReference": "order4552",
  "merchantInternalReference": "Order for a trip to Greece 20-27.08.2023",
  "payer": {
    "reference": "johndoe"

Request fields

Payment information
Field Status Description
currencyCode Required The three-letter ISO code for the payment currency.  A complete set of ISO currency codes can be found here.
For testing purposes, we suggest you start with a payment that uses the GBP currency.
amount Required Should be specified in minor units (cents, pence etc), with no decimal point.  
In the example, £123.45 is being requested, so is formatted as 12345 in the payment request.
type Required This indicates the purpose of payment.
Available options are BILL, GOODS (for physical goods only), PERSON_TO_PERSON, SERVICES or OTHER.
uniqueReference Required Create a reference of up to 18 characters, using letters and numbers only.
Each payment requires a unique reference and, to prevent duplicate payments, we’ll automatically reject requests where you’ve used the reference before.
merchantInternalReference Optional If a uniqueReference does not meet your requirements, you can use this field to create a reference of up to 100 characters (including special characters). If a value is provided for this field, you do not need to provide a uniqueReference – we will generate it automatically. Please note that merchantInternalReference will not be displayed to the shopper during their customer journey, only uniqueReference is visible on the checkout and bank statements. merchantInternalReference does not have to be unique – you may reuse it across multiple payments.
Payer identification fields

The Volt payment process also requires you to include additional information about the payer.  The minimum we require is payer.reference, the unique ID you use to identify the payer in your system.  You may also include the payer’s name, email address and ip address if you’re using Circuit Breaker, our fraud prevention plugin. 

Field Status Description
reference Required This should uniquely identify the payer in your system, and can be between 3 and 36 alphanumeric characters.
email Optional A valid email address for the payer, up to 255 characters.
name Optional The payer’s full name, also up to 255 characters.
ip Optional The payer’s IP address, in IPV4 format (

Additional callback redirect parameters

You can specify any custom parameters you’d like us to set in your redirect URLs by specifying a callback parameter, containing the values you’d like us to pass back in parameter=value format like this :-

"callback": "order_id=662384a0&sample=parameter"

Note, we cannot accept parameters called volt, volt-timed or volt-signature as these are reserved names for information we pass to the redirect URL.  Read more about the redirect process.

Successful request

If your request was successful, the response from this endpoint will contain a 201 Created status and the body will contain the ID and JWT token of your payment. You’ll need them in the next step.

  "id": "[UUID]", 
  "token": "[JWT_TOKEN]", 

Didn’t get a 201 status?

  • If you got a 400 error, check the body of your request to make sure it’s valid JSON
  • If you got a 401 or 403 status, check that you’re authenticated and that you passed the Authorization header containing a valid access token.
  • If you got a 404 error, check you’re posting to the correct /dropin-payments URL

Any other problems, please contact us on

Passing the payment information to your application (client-side)

The whole content of a body that you have received in a response from Volt’s API needs to be passed to your front-end application and saved as a payment.

Below you will find an example of how to initialise Volt Components on a server side. Please note that this is a simplified code that presents steps that need to be performed to create a payment. Actual implementation should take into account error handling, reusing and refreshing access token, passing actual payment and payer details etc.

export async function createVoltPaymentHandler(req, res) {
  // obtaining access token 
  const authParams = {
    grant_type: "password",
    client_id: CLIENT_ID,
    client_secret: CLIENT_SECRET,
    username: USERNAME,
    password: PASSWORD,

  const authResponse = await fetch("", {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
    body: querystring.stringify(authParams),

  const authData = await authResponse.json();

  const accessToken = authData.access_token;

  // create new payment
  const body = {
    currencyCode: "EUR",
    amount: 100,
    type: "BILL",
    uniqueReference: "sale123",
    payer: {
      reference: "payer485",

  const paymentResponse = await fetch("", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
    body: JSON.stringify(body),
  const paymentData = await paymentResponse.json();

  // return the payment creation result


Initialising and configuring Drop-in component (client-side)

As a next step you need to add the Volt Components JS library.

    <script src=""></script>

Addition of a placeholder div for a Volt Drop-in component is also required.

  <div id="volt-payment-component">
    <!-- Volt Drop-in component will be rendered here -->

To initialise Volt Components, use the code below.

const mode = "production" // sandbox/production
const volt = new window.Volt({ mode })

function async init() {
  const response = fetch(``)
  const payment = await response.json();

  const paymentContainer = volt.payment({
    language: "pl", // optional - ISO 639-1
    country: "PL", // optional - ISO 3166

  const paymentComponent = paymentContainer.createPayment();

Volt mode – there are two possibilities, you can either connect to the sandbox or production environment.

Please note that for the iFrame to display properly, the minimum width required is 320px. If this dimension is less than 320, we cannot guarantee that all components will display correctly.

Flow with banks requiring bank login details

Some banks in Germany and Italy require the collection of login credentials directly on our checkout due to a lack of open banking infrastructure on their side. For these banks, we need to keep the redirection to our checkout page to collect the required details. This means that, where the user selects one of these banks in an embedded checkout on a merchant’s site, they will be asked to continue the payment on a separate checkout page. They will be redirected to our checkout to provide the necessary information and finalise the payment.