Create payment

Create new payment request.

Authorization

Bearer

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key*string

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

Lengthlength <= 64

X-Volt-Api-Version*integer

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"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

currency*string

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

Length3 <= length <= 3

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?

Device used to call the endpoint.

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

paymentSystem*string

Payment system used to make a transfer.

Value in"OPEN_BANKING_EU" | "OPEN_BANKING_UK" | "NPP_PAY_TO_AU"

openBankingEU?

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

Object is required if paymentSystem is set to OPEN_BANKING_EU.

openBankingUK?

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

Object is required if paymentSystem is set to OPEN_BANKING_UK.

nppPayToAU?

Definition used for processing transfer with the Australian NPP (New Payments Platform).

Object is required if paymentSystem is set to NPP_PAY_TO_AU.

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 indicated 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

`application/json`

curl -X POST "https://gateway.sandbox.volt.io/payments" \  -H "Idempotency-Key: 85136c79cbf9fe36bb9d05d0639c70c265c18d37" \  -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",      "statementDescriptor": "Black coffee - big",      "validityPeriod": 1440,      "accountIdentifiers": {        "iban": "DE75512108001245126199"      }    },    "beneficiary": {      "name": "Jane Doe",      "accountIdentifiers": {        "iban": "PL10105000997603123456789123"      }    },    "communication": {      "notifications": {        "url": "https://mywebsite.com/webhooks"      },      "return": {        "urls": {          "unified": {            "url": "https://mywebsite.com/payment"          },          "success": {            "url": "https://mywebsite.com/payment/success"          },          "failure": {            "url": "https://mywebsite.com/payment/failed"          },          "pending": {            "url": "https://mywebsite.com/payment/pending"          },          "cancel": {            "url": "https://mywebsite.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": "SWIFT",
  "displayInfo": [
    {
      "key": "Product SKU",
      "value": "87ec73a0"
    }
  ],
  "createdAt": "2024-04-15T15:52:01+00:00",
  "updatedAt": "2005-08-15T15:52:01+00:00",
  "mandateId": null,
  "paymentInitiationFlow": {
    "status": "PROCESSING",
    "details": {
      "reason": "AWAITING_USER_REDIRECT",
      "redirect": {
        "url": "https://vo.lt/asqIs",
        "directUrl": "https://myBank.com/authorisation?code=xyz"
      }
    }
  }
}

{
  "code": "MISSING_HTTP_HEADER",
  "message": "Missing \"X-Volt-Initiation-Channel\" HTTP header."
}

{
  "code": "UNAUTHORISED",
  "message": "Unauthorised."
}

{
  "code": "ACCESS_DENIED",
  "message": "Access denied."
}

{
  "code": "IDEMPOTENCY_CONFLICT",
  "message": "Idempontency key already used."
}

{
  "code": "VALIDATION_FAILURE",
  "message": "Validation failed.",
  "errors": [
    {
      "type": "TOO_LONG",
      "propertyPath": "psdEurope.accountIdentifications.iban",
      "message": "IBAN must have a maximum of 36 characters"
    }
  ]
}

{
  "code": "INTERNAL_SERVER_ERROR",
  "message": "Something went wrong. Please, contact support. TraceId: b8cfd344-093c-4b8c-8fd4-f0e406060c3c. Timestamp: 1723193467."
}

Create payment

Authorization

Header Parameters

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

409application/json

422application/json

500application/json

Example Processing (awaiting user redirect)

Example Waiting for user input (account identification required)

Example Waiting for user input (SCA method required)

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`