How API works - Requesting payment

Requesting a payment

Volt’s Unified Global Payments API is at the core of all our integration channels, starting with the POST /payments endpoint. You’ll use this endpoint to initiate payments across all regions and checkout types.

While the global API parameters are consistent, some regional parameters may vary depending on the selected checkout type and local regulatory requirements. This structure allows you to integrate once and just include additional fields when enabling a new region.

API reference

The request payload must include all necessary payment details. Those details might differ between regions or markets. Global API distinguishes that by wrapping all market-specific details within dedicated objects.

Payment request payload contains generic information, which is market-agnostic, as well as market-specific part, pointed out by the paymentSystem property. paymentSystem property value tells the API which market-specific object in the payload we should look for.

POST /payments example

{
    "currency": "EUR",
    "amount": 10000,
    "internalReference": "XV9840MK550AMKQ910",
    "paymentSystem": "openBankingEU", // describe payment system used for payment processing
    "openBankingEU": { // corresponding market-specific details
        "type": "SERVICES",
        "institutionId": "dae814a8-cbc2-4670-813e-ae8f3c8d1119",
        "accountIdentifiers": {
            "iban": "DE75512108001245126199"
        }
    },
    "payer": {
        "reference": "JDOE-101",
        "firstName": "John",
        "lastName": "Doe",
        "organisationName": "JD Holdings",
        "email": "john@doe.com"
    },
    "device": {
        "ip": "192.168.0.1",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
        "fingerprint": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
    },
    "communication": {
        "return": {
            "urls": {
                "unified": "https://mywebsite.com/XV9840MK550AMKQ910"
            }
        }
    }
}

Responses from /payments requests always contain full payment request object. One of its elements is paymentInitiationFlow an object, which determines where the payment request is in the initiation process, and what needs to be done next.

GET /payments example

{
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "payer": {
        "email": "johndoe@example.com",
        "lastName": "Doe",
        "firstName": "John",
        "reference": "JDOE-101",
        "organisationName": "JD Holdings",
        "accountIdentifiers": {
            "iban": "DE75512108001245126199"
        }
    },
    "amount": 10000,
    "device": {
        "ip": "192.168.0.1",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
        "fingerprint": "2aae6c35c94fcfb415dbe95f408b9ce91ee846ed"
    },
    "sender": {
        "name": "John Doe",
        "accountIdentifiers": {
            "iban": "DE75512108001245126199"
        }
    },
    "status": "NEW_PAYMENT",
    "currency": "EUR",
    "createdAt": "2024-04-15T15:52:01+00:00",
    "updatedAt": "2005-08-15T15:52:01+00:00",
    "beneficiary": {
        "name": "Jane Doe",
        "accountIdentifiers": {
            "iban": "PL10105000997603123456789123"
        }
    },
    "transferType": "SWIFT",
    "openBankingEU": {
        "type": "BILL",
        "provider": "Volt",
        "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49",
        "validityPeriod": 1440,
        "accountIdentifiers": {
            "iban": "DE75512108001245126199"
        }
    },
    "paymentSystem": "OPEN_BANKING_EU",
    "paymentReference": "XV9840MK550AMKQ910",
    "internalReference": "H35X48Y4FWOD6G3S",
    "paymentInitiationFlow": {
        "status": "PROCESSING",
        "details": {
            "reason": "AWAITING_USER_REDIRECT",
            "redirect": {
                "url": "https://vo.lt/short",
                "directUrl": "https://myBank.com/authorisation?code=xyz"
            }
        }
    }
}

For detailed API reference, please visit

API reference