VoltDocs
Login to Fuzebox
Get startedAPI ReferenceImplementationBranding

Migration Guide

Guide for migrating from Payments API (legacy) to Global Unified Payments API

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.

Payments API (legacy)

POST api.volt.io/oauth
curl --location 'https://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'

Global API

POST gateway.volt.io/oauth
curl --location 'https://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
$.typeDepends 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.nameNot used anymore: firstName and lastName are now separate fields
$.payer.ip$.device.ip
$.shopper.reference$.payer.reference
$.shopper.email$.payer.email
$.shopper.firstName$.payer.firstName
$.shopper.lastName$.payer.lastName
$.shopper.organisationName$.payer.organisationName
$.shopper.ip$.device.ip
$.bankDepends on the selected $.paymentSystem, however the path is similar: $.{paymentSystemObject}.institutionId
$.callback$.communication.return.queryString
$.notificationUrl$.communication.notifications.url
$.paymentSuccessUrl$.communication.return.urls.success.url
$.paymentFailureUrl$.communication.return.urls.failure.url
$.paymentPendingUrl$.communication.return.urls.pending.url
$.paymentCancelUrl$.communication.return.urls.cancel.url
$.checkoutCountries$.checkout.hosted.countries.available
$.bankEditableNot 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

Example: EU Payment Request

Payments API (legacy)

POST api.volt.io/payments
{
    "currencyCode": "EUR",
    "amount": 12345,
    "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"
    },
    "type": "OTHER",
    "bank": "662384a0-9734-4556-a8bd-3f1e774e2a3c",
    "bankEditable": "true", 
    "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",
    "callback": "order_id=662384a0&sample=parameter",
    "checkoutCountries": [
        "PL",
        "DE"
    ],
    "summaryDetails": [
        {
            "label": "Category",
            "value": "Car Rental"
        },
        {
            "label": "Pickup",
            "value": "Heathrow T1"
        }
    ]
}

Global API

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": {
        "notifications": {
            "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"
        }
    },
    "checkout": {
        "hosted": {
            "countries": {
                "available": [
                    "PL",
                    "DE"
                ]
            }
        }
    }, 
    "displayInfo": [
        {
            "key": "Category",
            "value": "Car Rental"
        },
        {
            "key": "Pickup",
            "value": "Heathrow T1"
        }
    ]
}

Example: UK Payment Request

Payments API (legacy)

POST api.volt.io/payments
{
    "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"
        }
    ]
}

Global API

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": {
        "notifications": {
            "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

Payments API (legacy) Response

POST api.volt.io/payments
{
    "id": "93b85f3c-76eb-4316-b1ae-f3370ddc59bc",
    "checkoutUrl": "https://checkout.volt.io/93b85f3c-76eb-4316-b1ae-f3370ddc59bc?auth=jwtToken"
}

Global API Response

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.

Payments API (legacy)

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

Global API

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

Next Steps

To get started with the Global Payments API, please visit:

For detailed reference, please visit:

How is this guide?

Last updated on

Maintenance and changes

Understanding API changes and versioning policy

Overview

...

On this page

Migration Guide
Authenticating with the API
Payments API (legacy)
Global API
Create Payment Request HTTP Headers
Create Payment Request Payload Mapping
Example: EU Payment Request
Payments API (legacy)
Global API
Example: UK Payment Request
Payments API (legacy)
Global API
Create Payment Request Response
Payments API (legacy) Response
Global API Response
Get Payment's Match Score (Matchmeter)
Payments API (legacy)
Global API
Next Steps