Requesting 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.

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": "OPEN_BANKING_EU", // 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 the paymentInitiationFlow object, which determines where the payment request is in the initiation process, and what needs to be done next.

POST /payments response 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"
      }
    }
  }
}

Skip bank selection with IBAN-based bank auto-resolution

When you already know your payer's bank account (IBAN), you can hand it to Volt at payment creation and let Volt work out which bank to use automatically. This removes a step from the payment journey and lifts conversion. It helps both API integrations (no separate round-trip to choose the institution) and hosted checkout (Volt pre-selects the payer's bank, and can send the shopper straight to it).

The feature is driven by two request headers, used together with the payer IBAN in the request body:

X-Volt-Institution-Auto-Resolve — opt in to auto-resolution. When enabled, Volt derives the bank from the IBAN, applies it to the payment, and reports the outcome back in response headers.

X-Volt-Fast-Bank-Redirect — hosted checkout only. Once the bank is resolved, send the shopper straight to the bank's authorisation page, skipping the bank-selection screen.

When to use it

Use this feature when all of the following are true:

The payment is an Open Banking EU payment (paymentSystem: OPEN_BANKING_EU).

You already hold the payer's IBAN at the time you create the payment.

You initiate via either the hosted or the API channel. Note that fast bank redirect only affects hosted checkout — on the API channel there is no hosted checkout to skip.

If you don't have the IBAN, or you use a different payment system, create payments exactly as you do today — this feature simply won't apply.

Things to keep in mind

The payment is always created. A resolution miss is not a payment failure — it only changes whether a bank is pre-selected and whether the shopper skips bank selection.

Your own bank choice always wins. If you send openBankingEU.institutionId, auto-resolution is skipped entirely and your institution is used.

Some banks need extra details first. Even when the bank is resolved, certain banks require additional account information (for example an account number and branch code) before redirect. On hosted checkout the shopper provides those details first, then continues to the bank.

An invalid IBAN is rejected up front. If the IBAN fails validation, the request is rejected with a validation error (422) before any resolution happens.

For the full list of request and response headers, including every resolution outcome and error code, see the .

{
  "id": "d70cf67a-a4b2-449e-af9b-572e03609917",
  "checkoutUrl": "https://checkout.volt.io/d70cf67a-a4b2-449e-af9b-572e03609917?auth=jwtToken",
  // ... other payment fields
}

The checkoutUrl can be:

Used directly in your customer communication (email, SMS, invoice)

Encoded into a QR code for customers to scan

For more information about Pay by Link, including how to generate links from Fuzebox, see the .

For detailed API reference, please visit API Reference section.

Requesting payment

Skip bank selection with IBAN-based bank auto-resolution

When to use it

Things to keep in mind

Pay by Link

Minimum validity period

Response

API Reference

On this page