Embedded Checkout v1 (deprecated)

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.

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

Request a payment (server-side)

Authentication

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

Environment

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.

Location

Sandbox
Production

POST https://api.sandbox.volt.io/dropin-payments

POST https://api.volt.io/dropin-payments

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

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 support@volt.io

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("https://api.sandbox.volt.io/oauth", {
    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("https://api.sandbox.volt.io/dropin-payments", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(body),
  });
  const paymentData = await paymentResponse.json();

  // return the payment creation result
  res.json(paymentData);
}

createVoltPaymentHandler()

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

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

<html>
  <head>
    ...
    <script src="https://js.volt.io/v1"></script>
  </head>
  ...
</html>

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

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

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(`https://api.your-page.com/create-volt-payment`)
  const payment = await response.json();

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

  const paymentComponent = paymentContainer.createPayment();
  paymentComponent.mount("#volt-payment-component");
}

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.