Payouts via the API

Once the payout functionality is enabled for you, you will be able to pay out any amount, as long as you have sufficient balance in your account. Please note that you can’t go into overdraft. 

GET eligible beneficiaries

This step only applies to Payouts made to known beneficiaries, so-called “closed loop payouts”. 

In the closed-loop payout system, you may only send funds to beneficiaries who you’ve received funds from in the past 12 months. It’s therefore advisable to check that the account number or IBAN you’re sending to will be valid for a payout, before trying to create a new payout request.

This endpoint will provide a list of all eligible beneficiaries, based on money received from previously-initiated Volt Gateway Payments or Credits.  You may search by account number, IBAN or beneficiary name, by providing one or more of these items as query parameters.

Location

  • Sandbox
  • Production 
GET https://connect-api-sandbox.volt.io/payouts/beneficiaries
GET https://connect-api.volt.io/payouts/beneficiaries

Parameters

accountNumber Account number of the beneficiary account that you’d like to send a payout to
iban IBAN of the beneficiary account that you’d like to send a payout to
name Name of the beneficiary that you’d like to send a payout to.  

Note – the search will do partial matching on the name field, so if you search for John it will return all beneficiaries with names containing John

Sample response

In this example, we’re looking for a beneficiary to send a GBP payout to, using their account number.   Note that because there could be more than one match, beneficiaries are returned as an array.

GET /payouts/beneficiaries?accountNumber=12345678 
[
  {
  "name": "John Johnson",
  "accountNumber": "12345678",
  "sortCode": "404452",
  "iban": null,
  "swiftBic": null
  }
]

POST a new payout request

To create a payout request, you will need the account details. This may be an IBAN, IBAN + Swift BIC, account number + sort code, or other account identifiers depending on your region.

If you wish to straight through process these requests, then the API requests must be signed using a private key, for more details on this please refer here. 

Location

  • Sandbox
  • Production 
POST https://connect-api-sandbox.volt.io/payouts
POST https://connect-api.volt.io/payouts

Request headers

If you’re using a Volt Account, you’ll need to sign your request using an additional header.  If you’re using one of our Connected Accounts, you don’t need to include this header. You can only test this on production, as this header is ignored on sandbox.

Signing requests for key operations

Idempotency keys are optional, but recommended, to avoid duplicate POST requests.  Send a unique identifier for each request – we recommend using a UUID.  If the request times out, or you don’t receive a response or any other reason, you may safely retry the request using the same payload and headers.

Find out more about idempotency keys

  • Using a Volt Account
  • Using a Connected Account
All headers - idempotency key is optional, JWS signature is required 
Authorization: Bearer {Access Token}
Content-type: application/json
idempotency-key: {Your Unique Value}
X-JWS-Signature: {JWT Token}
All headers - idempotency key is optional 
Authorization: Bearer {Access Token}
Content-type: application/json
idempotency-key: {Your Unique Value}

Request body

  • SEPA payout
  • GBP payout
  • AUD payout
  • Other currencies 
{
  "amount": 12345,
  "currency": "EUR",
  "paymentTitle": "SEPA test",
  "beneficiary": {
    "name": "John Johnson",
    "iban": "DE07500105176551562526",
  },
  "externalReference": "Some reference"
}
{
  "amount": 12345,
  "currency": "GBP",
  "paymentTitle": "GBP test",
  "beneficiary": {
    "name": "John Johnson",
    "accountNumber": "12345678",
    "sortCode": "404777",
  },
  "externalReference": "Some reference"
}
{
    "amount": 12345,
    "currency": "AUD",
    "paymentTitle": "AUD test",
    "beneficiary": {
        "name": "John Johnson",
        "bsb": "012345",
        "accountNumber": "12345678",
        "email": "john@johnson.com"
    },
    "externalReference": "Some reference"
}
{
  "amount": 12345,
  "currency": "DKK",
  "paymentTitle": "Other currency test",
  "beneficiary": {
    "name": "John Johnson",
    "iban": "DE07500105176551562526",
    "swiftBic": "BIGBPLPW",
  },
  "externalReference": "Some reference"
}

Fields

Field name Type Description
amount integer In minor units, no decimal places
currency string (3) 3 letter ISO code for currencies
paymentTitle string Payment reference to be shown on statement
beneficiary object  
    name string Full name or organisation name
    iban string Required for SEPA
    swiftBic string Optional for SEPA
    accountNumber string UK and AU domestic payouts only
    sortCode string UK domestic payouts only
    bsb string Required for AU domestic payouts
    email string Required for AU domestic payouts
externalReference string|null Optional internal payout reference to be used for reconciliation and tracking within merchant systems. Not unique. Not shared with banks or payment networks. Maximum length is 255 chars.

Successful response

A successful request to create a Payout will result in an HTTP 201 Created response, with a body containing the ID of the Payout that was created.

GET list of payouts

To get a list of all the payouts you’ve created, call the GET /payouts endpoint with no parameters.

Parameters

Parameter Description
status The current status of the payout. Possible values are:

  • PAYOUT_CREATED
    PAYOUT_APPROVED_AUTOMATICALLY (for payouts created on API only)
  • PAYOUT_APPROVED_BY_USER (for payouts created on Fuzebox only)
  • PAYOUT_REJECTED_BY_USER (for payouts created on Fuzebox only)
  • PAYOUT_PROCESSING 
  • PAYOUT_FAILED
  • PAYOUT_INITIATED_AT_PROVIDER
  • PAYOUT_CONFIRMED
  • PAYOUT_REJECTED_BY_PROVIDER

Location 

  • Sandbox
  • Production 
GET https://connect-api-sandbox.volt.io/payouts
GET https://connect-api.volt.io/payouts

Sample response

[
  {
    "id":"efffed42-40f7-4bd2-840d-908aae9a33ad",
    "status":"PAYOUT_CREATED",
    "createdAt":"2019-08-24T14:15:22Z",
    "amount":500,
    "currency":"EUR",
    "paymentTitle":"Payout123456",
    "beneficiary":{
      "name":"John Johnson",
      "accountNumber":"12345678",
      "sortCode":"404452",
      "iban":"DK8389009999910135",
      "swiftBic":"SXPYDKKKXXX"
    },
    "sender":{
      "sortCode":"404777",
      "accountNumber":"87654321",
      "iban":"DK8389009999910135",
      "swiftBic":"SXPYDKKKXXX"
    },
    "externalReference": null
  }
]

GET payout details

To get details of a payout, you’ll need the id returned when you created the payout.

Location

  • Sandbox
  • Production 
GET https://connect-api-sandbox.volt.io/payouts/{id}
GET https://connect-api.volt.io/payouts/{id}

Parameters

id id of the payout, as returned by the create payout endpoint

Sample responses

  1. Where the payout was created using the API so did not require approval.
GET /payouts/efffed42-40f7-4bd2-840d-908aae9a33ad 
{
  "id":"efffed42-40f7-4bd2-840d-908aae9a33ad",
  "status":"PAYOUT_APPROVED_AUTOMATICALLY",
  "createdAt":"2019-08-24T14:15:22Z",
  "amount":500,
  "currency":"EUR",
  "paymentTitle":"Payout123456",
  "beneficiary":{
    "name":"John Johnson",
    "accountNumber":"12345678",
    "sortCode":"404452",
    "iban":"DK8389009999910135",
    "swiftBic":"SXPYDKKKXXX"
  },
  "sender":{
    "sortCode":"40477"7,
    "accountNumber":"87654321",
    "iban":"DK8389009999910135",
    "swiftBic":"SXPYDKKKXXX"
  },
  "approvals":[],
  "externalReference": "Some reference"
}
  1. Where the Payout was created in Fuzebox but was rejected by another user and cannot be paid out.  The approving user’s decision is recorded in the approvals section and the final status code is stored in status.  
GET /payouts/94fcc71e-6244-4f77-a86b-99eb7601b843 
{
  "id":"efffed42-40f7-4bd2-840d-908aae9a33ad",
  "status":"PAYOUT_REJECTED_BY_USER",
  "createdAt":"2019-08-24T14:15:22Z",
  "amount":500,
  "currency":"EUR",
  "paymentTitle":"Payout123456",
  "beneficiary":{
    "name":"John Johnson",
    "accountNumber":"12345678",
    "sortCode":"404452",
    "iban":"DK8389009999910135",
    "swiftBic":"SXPYDKKKXXX"
  },
  "sender":{
    "sortCode":"404777",
    "accountNumber":"87654321",
    "iban":"DK8389009999910135",
    "swiftBic":"SXPYDKKKXXX"
  },
  "approvals":[
    {
      "user":{
        "name":"Robert Robertson"
      },
      "type":"REJECTION",
      "createdAt":"2019-08-24T14:15:22Z"
    }
  ],
  "externalReference": "Some reference"
}
← Previous Introduction to payouts
Next → Payouts via Fuzebox