Integration of Volt Embedded Checkout

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

  1. Requesting a payment (server-side)
  2. Configuring and rendering the drop-in component (client-side)
  3. Rendering Volt Checkout on your client (client-side)

Requesting a payment (server-side)

Note that you have to authenticate first before you can request a payment. API Authentication.

Request
POST /dropin
{
    "currencyCode": "EUR",
    "amount": 100,
    "type": "OTHER",
    "uniqueReference": "123456789",
    "shopper": {
        "reference": "123456789",
        "email": "firstname.lastname@example.com",
        "firstName": "Firstname",
        "lastName": "Lastname",
        "ip": "150.160.170.180"
    },
    "callback": "order_id=662384a0&sample=parameter"
}
Request in API docs Try yourself with our Postman Collection.

The details of the request header and body are described in our API docs.

The shopper.reference is used by our systems to identify returning shoppers. It should follow an identifier you already use, e.g. a user id. In case you use sensitive data we suggesting hashing it before sharing it with Volt.

Identifier returning shoppers is especially useful for Circuit Breaker as it allows you to configure rules and limitations for specific shoppers to prevent abnormal or unwanted behaviour.

Additional callback redirect parameters

You can define a string of parameters in callback. Volt attaches this string to the payment return URLs. For example

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

Do not use the parameters volt, volt-signature and the volt-timestamp as Volt already uses them.

See more about the redirect return process

Response

Payment is not visible in Fuzebox until bank redirect

Payments created with Volt Embedded Checkout are only logged to our database after the shopper gets redirected to the bank. Until this point, those payments won’t be visible in Volt Fuzebox.

Response
{
    "id": "509c7915-0e16-4927-9b73-efd629e9273a",
    "token": "eyJ...5sQ"
}

A successful payment request returns an id and a token. This id is a unique identifier for this payment once it is created. We recommend storing it in your system for any future reference.

The Volt Embedded Checkout requires both values to get rendered on the client. Pass both to your client application.

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

Add the Volt JavaScript library to your client HTML.

Volt JavaScript library
<script src="https://js.volt.io/v1"></script>

Add a placeholder div for a Volt Drop-in. Set it in place where you want the Volt Embedded Checkout to render. For that Volt uses the element’s id, here #volt-payment-component.

Placeholder for Volt Embedded Checkout
<div id="volt-payment-component">
    <!-- Volt Drop-in component will be rendered here -->
</div>

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.

Render Volt Embedded Checkout

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.

Basic HTML example for the client
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <title>Your client</title>
        <!-- This is the Volt JS library -->
        <script src="https://js.volt.io/v1"></script>
    </head>
    <body>
        <h1>Volt Embedded Checkout</h1>
        <div id="volt-payment-component">
            <!-- Volt Drop-in component will be rendered here -->
        </div>
        <script>
            const mode = "sandbox"; // sandbox/production
            const volt = new window.Volt({ mode });
            
            function init() {
                // The payment object is the response from the payment request.
                // Replace it with your server response.
                payment = {
                    "id": "509c7915-0e16-4927-9b73-efd629e9273a",
                    "token": "eyJ...5sQ"
                }
                
                paymentContainer = volt.payment({
                    payment,  // Payment response from the server, containing id and token.
                    language: "en", // optional - ISO 639-1
                    country: "PL", // optional - ISO 3166
                });

                // Fetch when the language is changed
                paymentContainer.on("languageChange",(e)=>{
                    console.log("Changed language to: " + e.language)
                });
                // Fetch when the country is changed
                paymentContainer.on("countryChange",(e)=>{
                    console.log("Changed country to: " + e.country)
                });
                paymentContainer.on("error",(e)=>{
                    console.log("Error " + e.code + " message: \"" + e.message + "\"")
                });
                
                paymentComponent = paymentContainer.createPayment();
                
                paymentComponent.mount("#volt-payment-component");
            }
            // Render Volt Embedded Checkout
            init();
        </script>
    </body>
</html>

Updating Payment Request Details

Embedded Checkout (v2) allows to modify the amount of the payment request after it was already created. This allows to add some additional options to the order while the payer is already on the checkout page.

Please note that you are only eligible to modify those payment request details until the payer gets redirected to the bank. After that, it is no longer possible.

Modifying payment request details is possible by making a request to Volt API from your backend application. This request should contain an authorization header, similar to creating a new embedded checkout. All of the options you can see in the example are available for change. If you don’t need to update all of them at once, you can pick just those that match your use case.

PATCH /dropin/{dropinPaymentRequestId}
Authorization: Bearer <token>
Request:
{
  "amount": 100
}

Response:
{
  "id": "fc89fd80-ba96-406f-b4ff-f9e0dd4a5907",
  "token": "someToken"
}

After receiving a successful response, the payment request has been modified. After that, we will inform the payer about those changes in a form of a pop-up, after he clicks the “Pay” button, or when he will try to change the bank.

After confirming, the payer can continue with payment as usual.

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. In the case of those banks, if the payer will pick one from the list, there is no option available for updating payment request details. 

For these flows, embedded checkout payment requests will be treated as new payments only after the payer picks one of the banks from list. Until this point, those payments won’t be visible in Volt Fuzebox.

The shopper returns to one of the payment urls

From hereon the shopper continues back in your experience. See returning the shopper to you.