Integration guide

The integration of our embedded checkout contains the following 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)

Creating a payment (server-side)

Before you start making requests to Volt API you need to authenticate yourself. The authentication process is common for Hosted and Drop-in components. This process is explained here.

When the authentication process is finished, you can start creating a payment.

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.

Request  body

  • Sandbox
  • Production
POST https://api.sandbox.volt.io/dropin-payments
{
    "currencyCode": "EUR",
    "amount": 12345,
    "type": "OTHER",
    "uniqueReference": "order4552",
    "payer": {
      "reference": "johndoe"
    }
}
POST https://api.volt.io/dropin-payments
{
    "currencyCode": "EUR",
    "amount": 12345,
    "type": "OTHER",
    "uniqueReference": "order4552",
    "payer": {
      "reference": "johndoe"
    }
}

Request fields

currencyCode should be a 3-letter code in ISO 4217 format – for example GBP, EUR, USD.

amount should not include any decimal places but should be an integer number in the minor currency unit – that is cents or pence, rather than dollars, euros or pounds. In the example, we’re requesting £123.45.

type should be one of BILL, GOODS, PERSON_TO_PERSON, SERVICES or OTHER – choose the most appropriate code for the payment you’re requesting.

uniqueReference should be a maximum of 18 characters and should contain letters and numbers only. As implied, you cannot use the same reference for multiple payments.

payer should include at least the reference field which uniquely identifies a user in your system.

Response

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.