Migration guide

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

The current Payments API will be deprecated for payment creation with the hosted checkout. Volt plans to drop support of the Payments API by the end of 2025.

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

Authenticating with the API

Before using any endpoint in Volt’s APIs, you’ll need to authenticate using the /oauth endpoint. This is true for the (legacy) Payments API as well as the Global API. There is, however, a small difference between the two. The Payments API uses application/x-www-form-urlencoded as a content type (set in the Content-Type HTTP header), while the Global API uses application/json as a content type. This results in a slightly 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 the (legacy) Payments API and the Global API in terms of HTTP headers while creating a new payment request. The below table shows the difference in HTTP headers between the 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 for the request; it is recommended using UUID 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

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

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

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

Payments API (legacy) Global API
$.currencyCode $.currency
$.amount $.amount
$.type Depends on the selected $.paymentSystem, however the 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 the 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
$.beneficiary.name $.beneficiary.name
$.beneficiary.iban $.beneficiary.accountIdentifiers.iban
$.beneficiary.swiftBic $.beneficiary.accountIdentifiers.swiftBic
$.beneficiary.sortCode $.beneficiary.accountIdentifiers.sortCode
$.beneficiary.accountNumber $.beneficiary.accountIdentifiers.accountNumber
  • 🇪🇺 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 the payment request is created, you should redirect the payer to Volt’s hosted checkout. The below table shows where the redirect URL appears differently in the response between the (legacy) Payments API and the 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"
            }
        }
    }
}

Get payment's match score (Matchmeter)

Volt’s Matchmeter API has also been changed, both in available query parameters as well as response content.

The below comparison shows the difference in request and response, between the (legacy) Payments API endpoint for Matchmeter and the Global API endpoint.

GET api.volt.io/payments/{id}/name-match-score?allow_initials=true (legacy) 
{
    "invocationId": "e9725468-0858-4dbb-af72-1e49c8254d68",
    "nameMatchScore": 0.89
}
GET gateway.volt.io/payments/{id}/name-match-score?allowInitials=true 
{
    "invocationId": "e9725468-0858-4dbb-af72-1e49c8254d68",
    "score": 0.89
}

To get started with the Global Payments API, please visit

Get started with the Global Payments API

For detailed reference, please visit

Global Payments API reference