Payments APIPayments

Create payment

POST
/payments

Create new payment request.

Authorization

Bearer
headerAuthorizationBearer <token>

Bearer token using a JWT.

Header Parameters

Idempotency-Key*string

It helps prevent duplicates in your POST requests. We recommend using a UUID for the key, however you may use any other unique identifier you choose.

Lengthlength <= 64
X-Volt-Api-Version*1

Version of the API used. Currently, version 1 is the only version.

Value in1
X-Volt-Initiation-Channel*string

Channel used for payment initiation flow.

Value in"api""hosted"
X-Volt-Institution-Auto-Resolve?string

Opt in to IBAN-based bank auto-resolution. When true, Volt resolves the institution from the payer IBAN (openBankingEU.accountIdentifiers.iban), applies it to the payment, and reports the outcome in the X-Volt-Institution-Auto-Resolved, X-Volt-Institution-Resolution-Source and X-Volt-Institution-Resolution-Error response headers. When false or omitted, no resolution is applied and no outcome headers are returned.

The value is compared case-insensitively; only true enables the option. Any other value, including a missing or empty header, is treated as false. The payment is always created (201) regardless of the resolution outcome.

Value in"true""false"
X-Volt-Fast-Bank-Redirect?string

Hosted checkout only. When a bank has been resolved (see X-Volt-Institution-Auto-Resolve), send the payer straight to the bank's authorisation page instead of to the checkout bank-selection screen.

Has no effect unless a bank was resolved, and no effect on the api channel. The value is compared case-insensitively; only true enables the option.

Value in"true""false"
X-Volt-Verified-Payment?string

Create the payment as a verified payment. Volt verifies that the payer owns the source account and matches their name against the bank record, then pauses for your approval decision (the CUSTOMER_APPROVAL required input) before the payment is sent to the bank.

Adding this header is the only change required; the rest of the POST /payments body is unchanged. The value is compared case-insensitively; only true enables the option. Any other value, including a missing or empty header, is treated as false. Verified payments require an institution that supports account verification.

Value in"true""false"

Request Body

application/json
  1. body

OpenBanking EU payment creation request body.

currency*"EUR"

Currency in which the payment should be made, in ISO 4217 format (3 uppercase letters).

Length3 <= length <= 3
Value in"EUR"
amount*integer

The amount of the transaction in fractional unit (pence, cents etc).

Range0 < value
paymentReference?string

Unique reference for the payment from the partner's system. Reference must contain only alphanumeric characters.

If value is not provided, it will be generated by Volt.

Lengthlength <= 18
internalReference?string

Identifier of the transaction in the partner's system. This field can contain up to 100 characters, including special ones.

Despite field being optional, we recommend to set this value.

Lengthlength <= 100
payer*

Information about the payer.

device?
paymentSystem*"OPEN_BANKING_EU"

Payment system used to make a transfer.

Value in"OPEN_BANKING_EU"
openBankingEU*

Definition used for processing transfer with the PSD directive (Open Banking).

Object is required if paymentSystem is set to OPEN_BANKING_EU.

beneficiary?

Only use these fields if you are approved by Volt for the dynamic beneficiary feature. Dynamic beneficiary allows you to initiate transfers to a different bank account per payment, within a pool of addresses pre-approved by Volt. The most common use case is initiating transfers to individual IBANs assigned to user wallets.

communication?

Settings for establishing communication back to the partner.

Object is required when X-Volt-Initiation-Channel is api.

displayInfo?array<>

Key-value pairs useful for passing some additional information to be displayed on checkout.

Itemsitems <= 5
termsAndConditionsAccepted?boolean

Flag indicating that T&C has been presented to the payer and accepted by the payer.

This field is required when X-Volt-Initiation-Channel is api.

If value is different than true, validation will fail.

checkout?

Checkout's additional configuration.

At the moment, it only supports Volt's hosted checkout. Configuration sent is taken into consideration only when X-Volt-Initiation-Channel is hosted.

Response Body

Created - The payment request was validated, created, and payment details returned.

Bank auto-resolution response headers

Returned only when the request was sent with X-Volt-Institution-Auto-Resolve: true. The payment is always created (201) regardless of the resolution outcome.

HeaderValuesDescription
X-Volt-Institution-Auto-Resolvedtrue, falsetrue when exactly one institution was resolved from the IBAN and applied to the payment; false otherwise.
X-Volt-Institution-Resolution-SourceIBANWhat the resolution was based on. Currently always IBAN.
X-Volt-Institution-Resolution-Errorsee belowPresent only when X-Volt-Institution-Auto-Resolved is false.

X-Volt-Institution-Resolution-Error carries one of:

ErrorMeaning
INSTITUTION_ID_PROVIDED(informational) openBankingEU.institutionId was supplied, so auto-resolution was skipped and that institution is used.
IBAN_NOT_PROVIDED(informational) No IBAN was present in the request, so there was nothing to resolve.
BIC_NOT_FOUNDThe IBAN is structurally valid and its country supported, but no matching BIC was found in the bank directory.
BIC_NOT_SUPPORTEDThe IBAN's country is not supported for Open Banking EU, or a BIC was found but no available Open Banking institution matches it.
MULTIPLE_INSTITUTIONSThe IBAN maps to more than one possible institution, so it cannot be chosen unambiguously.
UNKNOWN_ERRORAn unexpected error occurred while resolving the institution.
application/json
  1. response
id*string

Identifier of the payment.

Formatuuid
currency*string

Currency in which the payment is made, in ISO 4217 format (3 uppercase letters).

amount*integer

The amount of the transaction in fractional unit (pence, cents etc).

paymentReference*string

Payment reference provided by the partner (or generated by Volt). Used for reconciliation, visible on the bank statement.

Lengthlength <= 18
internalReference*|

Identifier of the transaction in the partner's system.

paymentSystem*"OPEN_BANKING_EU"

Payment system used to make a transfer.

Value in"OPEN_BANKING_EU"
openBankingEU*

Definition used for processing transfer with the PSD directive (Open Banking). Object is present in the response if paymentSystem is set to OPEN_BANKING_EU.

payer*

Information about the payer.

sender*

Information about the source account (sender).

beneficiary*

Information about the target account (beneficiary).

device*

Device used to call the endpoint for payment creation.

status*StatusEnum

Status of the transaction.

Value in"NEW_PAYMENT""APPROVED_BY_RISK""REFUSED_BY_RISK""BANK_REDIRECT""ADDITIONAL_AUTHORIZATION_REQUIRED""AUTHORISED_BY_USER""ERROR_AT_BANK""REFUSED_BY_BANK""DELAYED_AT_BANK""COMPLETED""NOT_RECEIVED""RECEIVED""FAILED""CANCELLED_BY_USER""ABANDONED_BY_USER""AWAITING_CHECKOUT_AUTHORISATION""ACCOUNT_SELECTION""REQUIRED_REDEEM""PAYOUT_INITIATED""SETTLED""UNKNOWN""PROVIDER_COMMUNICATION_ERROR"
transferType*|

Payment scheme used to make a transaction.

displayInfo*array<>

Additional information (key-value pairs) to be displayed on checkout.

createdAt*string

Date of payment creation.

Formatdate-time
updatedAt?|

Date of payment's last update.

Formatdate-time
paymentInitiationFlow*

Payment initiation flow object. It steers the initiation flow.

curl -X POST "https://example.com/payments" \  -H "Idempotency-Key: string" \  -H "X-Volt-Api-Version: 1" \  -H "X-Volt-Initiation-Channel: api" \  -H "Content-Type: application/json" \  -d '{    "currency": "EUR",    "amount": 10000,    "internalReference": "H35X48Y4FWOD6G3S",    "paymentReference": "T1Qwerty",    "payer": {      "reference": "JDOE-101",      "firstName": "John",      "lastName": "Doe",      "organisationName": "JD Holdings",      "email": "johndoe@example.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"    },    "paymentSystem": "OPEN_BANKING_EU",    "openBankingEU": {      "type": "SERVICES",      "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49",      "validityPeriod": 1440,      "accountIdentifiers": {        "iban": "DE75512108001245126199"      }    },    "beneficiary": {      "name": "Jane Doe",      "accountIdentifiers": {        "iban": "PL10105000997603123456789123"      }    },    "communication": {      "notifications": {        "url": "https://example.com/webhooks"      },      "return": {        "urls": {          "unified": {            "url": "https://example.com/payment"          },          "success": {            "url": "https://example.com/payment/success"          },          "failure": {            "url": "https://example.com/payment/failed"          },          "pending": {            "url": "https://example.com/payment/pending"          },          "cancel": {            "url": "https://example.com/payment/cancelled"          }        },        "queryString": "id=xyz"      }    },    "displayInfo": [      {        "key": "Product SKU",        "value": "87ec73a0"      }    ],    "termsAndConditionsAccepted": true  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "currency": "EUR",  "amount": 10000,  "paymentReference": "XV9840MK550AMKQ910",  "internalReference": "H35X48Y4FWOD6G3S",  "paymentSystem": "OPEN_BANKING_EU",  "openBankingEU": {    "type": "BILL",    "institutionId": "cdae5c01-a629-4362-be56-52101ec22a49",    "validityPeriod": 1440,    "provider": "Volt",    "accountIdentifiers": {      "iban": "DE75512108001245126199"    }  },  "payer": {    "reference": "JDOE-101",    "firstName": "John",    "lastName": "Doe",    "organisationName": "JD Holdings",    "email": "johndoe@example.com",    "accountIdentifiers": {      "iban": "DE75512108001245126199"    }  },  "sender": {    "name": "John Doe",    "accountIdentifiers": {      "iban": "DE75512108001245126199"    }  },  "beneficiary": {    "name": "Jane Doe",    "accountIdentifiers": {      "iban": "PL10105000997603123456789123"    }  },  "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"  },  "status": "NEW_PAYMENT",  "transferType": "SEPA Credit Transfer (within SEPA Zone)",  "displayInfo": [    {      "key": "Product SKU",      "value": "87ec73a0"    }  ],  "createdAt": "2024-04-15T15:52:01+00:00",  "updatedAt": "2005-08-15T15:52:01+00:00",  "paymentInitiationFlow": {    "status": "PROCESSING",    "details": {      "reason": "AWAITING_USER_REDIRECT",      "redirect": {        "url": "https://vo.lt/asqIs",        "directUrl": "https://myBank.com/authorisation?code=xyz"      }    }  }}

Global Payments API

View OpenAPI schemas.

Cancel payment POST

Cancel payment request.