Migration guide

This guide is designed to help you transition from current Payments API to new Global Unified Payments API (Global API). Migrating to Global API will not only help you stay current with the latest advancements but also ensure long-term support and maintainability.

Current Payments API in area of payment creation and hosted checkout is deprecated. Volt plans to drop support of it by the end of 2025.

This guide relates to hosted checkout integration for 🇪🇺 EU and 🇬🇧 UK.

Authenticating with the API

Before using any endpoint in the Volt’s APIs, you’ll need to authenticate using /oauth endpoint. This is true for (legacy) Payments API, as well as Global API. There is, however, a small difference between the two. Payments API uses application/x-www-form-urlencoded as a content type (set in Content-Type HTTP header), while Global API uses application/json as a content type. This results in a bit different request.

POST api.volt.io/oauth (legacy) 
curl --location 'http://api.volt.io/oauth' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=password' \
--data-urlencode 'client_id=6b288347-5d6f-4596-b620-72dc7a88de86' \
--data-urlencode 'client_secret=caaf7b1b-1024-4212-a55f-041007917ba8' \
--data-urlencode 'username=d0d6a7bd-780a-498a-95e4-402ec1b89c44@volt.io' \
--data-urlencode 'password=secretpassword'
POST gateway.volt.io/oauth 
curl --location 'http://gateway.volt.io/oauth' \
--header 'Content-Type: application/json' \
--data-raw '{
    "grant_type":"password",
    "client_id": "6b288347-5d6f-4596-b620-72dc7a88de86",
    "client_secret": "caaf7b1b-1024-4212-a55f-041007917ba8",
    "username":"d0d6a7bd-780a-498a-95e4-402ec1b89c44@volt.io",
    "password":"secretpassword"
}'

Create payment request HTTP headers

There are some changes between (legacy) Payments API and Global API in terms of HTTP headers while creating a new payment request. Below table shows the difference in HTTP headers between those two APIs.

Payments API (legacy) Global API
  • Authorization – access token obtained from POST /oauth response,
  • X-Volt-Api-Version – version of the API (from 1 to 4/edge).
  • Authorization – access token obtained from POST /oauth response,
  • Idempotency-Key – a unique identifier of the request; it is recommended using UUIDm however you may use any other unique identifier you choose,
  • X-Volt-Api-Version – version of the API; set 1,
  • X-Volt-Initiation-Channel – channel used for payment initiation flow; set hosted.

Create payment request payload mapping

Below table shows how to map payload from (legacy) Payments API POST endpoint(s) to Global API POST endpoint.

$.paymentSystem is a new property declaring which payment system should be used to make the transfer.

If payment system is OPEN_BANKING_EU, corresponding $.openBankingEU object is required.
If payment system is OPEN_BANKING_UK, corresponding $.openBankingUK object is required.

Payments API (legacy) Global API
$.currencyCode $.currency
$.amount $.amount
$.type Depends on the selected $.paymentSystem, however path is similar: $.{paymentSystemObject}.type
$.uniqueReference $.paymentReference (Note: this field is now optional.)
$.merchantInternalReference $.internalReference
$.payer.reference $.payer.reference
$.payer.email $.payer.email
$.payer.name Not used anymore.
$.payer.ip $.device.ip (Note: this field is now required.)
$.shopper.reference $.payer.reference
$.shopper.email $.payer.email
$.shopper.firstName $.payer.firstName
$.shopper.lastName $.payer.lastName
$.shopper.organisationName $.payer.organisationName
$.shopper.ip $.device.ip (Note: this field is now required.)
$.bank Depends on the selected $.paymentSystem, however path is similar: $.{paymentSystemObject}.institutionId
$.callback $.communication.return.queryString
$.notificationUrl $.communication.notifications.url
$.paymentSuccessUrl $.communication.return.urls.success
$.paymentFailureUrl $.communication.return.urls.failure
$.paymentPendingUrl $.communication.return.urls.pending
$.paymentCancelUrl $.communication.return.urls.cancel
$.checkoutCountries Not used anymore.
$.bankEditable Not used anymore
$.summaryDetails $.displayInfo
$.summaryDetails.[].label $.displayInfo.[].key
$.summaryDetails.[].value $.displayInfo.[].value
  • 🇪🇺 EU
  • 🇬🇧 UK
POST api.volt.io/payments (legacy) 
{
    "currencyCode": "EUR",
    "amount": 12345,
    "type": "OTHER",
    "uniqueReference": "sale123456",
    "merchantInternalReference": "1d73dd8a-4aef-4c83-80aa-f06c4f615a75",
    "shopper": {
        "reference": "user-13489",
        "documentId": "90971226008",
        "email": "john.smith@example.com",
        "firstName": "John",
        "lastName": "Smith",
        "organisationName": "Company",
        "ip": "122.118.64.13"
    },
    "bank": "662384a0-9734-4556-a8bd-3f1e774e2a3c",
    "bankEditable": "true", 
    "callback": "order_id=662384a0&sample=parameter",
    "notificationUrl": "https://client.app.example/notify",
    "paymentSuccessUrl": "https://example.com/redirect/success",
    "paymentFailureUrl": "https://example.com/redirect/failure",
    "paymentPendingUrl": "https://example.com/redirect/pending",
    "paymentCancelUrl": "https://example.com/redirect/cancel",
    "checkoutCountries": [
        "PL",
        "DE"
    ],
    "summaryDetails": [
        {
            "label": "Category",
            "value": "Car Rental"
        },
        {
            "label": "Pickup",
            "value": "Heathrow T1"
        }
    ]
}
POST gateway.volt.io/payments 
{
    "currency": "EUR",
    "amount": 12345,
    "paymentReference": "sale123456",
    "internalReference": "1d73dd8a-4aef-4c83-80aa-f06c4f615a75",
    "payer": {
        "reference": "user-13489",
        "firstName": "John",
        "lastName": "Smith",
        "organisationName": "Company",
        "email": "john.smith@example.com"
    },
    "device": {
        "ip": "122.118.64.13"
    },
    "paymentSystem": "OPEN_BANKING_EU",
    "openBankingEU": {
        "type": "OTHER",
        "institutionId": "662384a0-9734-4556-a8bd-3f1e774e2a3c"
    },
    "communication": {
        "notification": {
            "url": "https://client.app.example/notify"
        },
        "return": {
            "urls": {
                "success": {
                    "url": "https://example.com/redirect/success"
                },
                "failure": {
                    "url": "https://example.com/redirect/failure"
                },
                "pending": {
                    "url": "https://example.com/redirect/pending"
                },
                "cancel": {
                    "url": "https://example.com/redirect/cancel"
                }
            },
            "queryString": "order_id=662384a0&sample=parameter"
        }
    },
    "displayInfo": [
        {
            "key": "Category",
            "value": "Car Rental"
        },
        {
            "key": "Pickup",
            "value": "Heathrow T1"
        }
    ]
}
POST api.volt.io/payments (legacy) 
{
    "currencyCode": "GBP",
    "amount": 12345,
    "type": "OTHER",
    "uniqueReference": "sale123456",
    "merchantInternalReference": "1d73dd8a-4aef-4c83-80aa-f06c4f615a75",
    "shopper": {
        "reference": "user-13489",
        "documentId": "90971226008",
        "email": "john.smith@example.com",
        "firstName": "John",
        "lastName": "Smith",
        "organisationName": "Company",
        "ip": "122.118.64.13"
    },
    "bank": "662384a0-9734-4556-a8bd-3f1e774e2a3c",
    "callback": "order_id=662384a0&sample=parameter",
    "notificationUrl": "https://client.app.example/notify",
    "paymentSuccessUrl": "https://example.com/redirect/success",
    "paymentFailureUrl": "https://example.com/redirect/failure",
    "paymentPendingUrl": "https://example.com/redirect/pending",
    "paymentCancelUrl": "https://example.com/redirect/cancel",
    "checkoutCountries": [
        "PL",
        "DE"
    ],
    "summaryDetails": [
        {
            "label": "Category",
            "value": "Car Rental"
        },
        {
            "label": "Pickup",
            "value": "Heathrow T1"
        }
    ]
}
POST gateway.volt.io/payments 
{
    "currency": "GBP",
    "amount": 12345,
    "paymentReference": "sale123456",
    "internalReference": "1d73dd8a-4aef-4c83-80aa-f06c4f615a75",
    "payer": {
        "reference": "user-13489",
        "firstName": "John",
        "lastName": "Smith",
        "organisationName": "Company",
        "email": "john.smith@example.com"
    },
    "device": {
        "ip": "122.118.64.13"
    },
    "paymentSystem": "OPEN_BANKING_UK",
    "openBankingUK": {
        "type": "OTHER",
        "institutionId": "662384a0-9734-4556-a8bd-3f1e774e2a3c"
    },
    "communication": {
        "notification": {
            "url": "https://client.app.example/notify"
        },
        "return": {
            "urls": {
                "success": {
                    "url": "https://example.com/redirect/success"
                },
                "failure": {
                    "url": "https://example.com/redirect/failure"
                },
                "pending": {
                    "url": "https://example.com/redirect/pending"
                },
                "cancel": {
                    "url": "https://example.com/redirect/cancel"
                }
            },
            "queryString": "order_id=662384a0&sample=parameter"
        }
    },
    "displayInfo": [
        {
            "key": "Category",
            "value": "Car Rental"
        },
        {
            "key": "Pickup",
            "value": "Heathrow T1"
        }
    ]
}

Create payment request response

After payment request is created, you should redirect the payer to Volt’s checkout. Below table shows the difference where redirect URL appears in the response between (legacy) Payments API and Global API.

Payments API (legacy) Global API
$.checkoutUrl $.paymentInitiationFlow.details.redirect.url (QR code friendly), alternatively $.paymentInitiationFlow.details.redirect.directUrl
POST api.volt.io/payments (legacy) 
{
    "id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc",
    "checkoutUrl": "https://checkout.volt.io/93b85f3c-76eb-4316-b1ae-f3370ddc59bc?auth=jwtToken"
}
POST gateway.volt.io/payments 
{
    "id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc",
    //...
    "paymentInitiationFlow": {
        "status": "PROCESSING",
        "details": {
            "reason": "AWAITING_USER_REDIRECT",
            "redirect": {
                "url": "https://vo.lt/asqIs",
                "directUrl": "https://checkout.volt.io/93b85f3c-76eb-4316-b1ae-f3370ddc59bc?auth=jwtToken"
            }
        }
    }
}

To get started with Global Payments API, please visit

Get started with Global Payments API

For detailed reference, please visit

Global Payments API reference