Payouts via the API

With Connect payouts, you will be able to pay money out to anyone you’ve received money from in the past using Volt Connect.  You can pay out any amount, as long as you have sufficient funds in your Connect account.

API integration is now available on our Sandbox environment, in preparation for the product launch at the end of H2 2023.

GET eligible beneficiaries

As payouts are a closed-loop system, you may only send funds to beneficiaries who you’ve previously received funds from through Volt Connect.  You should therefore 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 previously initiated payments.  You may search by account number, IBAN or beneficiary name by providing one or more of these items as query parameters.

Location

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

Parameters

accountNumber Account number that you’d like to send a payout to
iban IBAN 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

Looking for an beneficiary by account number to send a GBP payout to. 

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

POST new payout request

To create a payout request, you will need the account details of a payer you’ve already received money from in the past.  This may be an IBAN, IBAN and Swift BIC, or account number and sort code.

Location

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

Headers

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 for any other reason, you may safely retry it using the same payload and headers.  More information on idempotency keys can be found in the API documentation.

Authorisation: Bearer {Access token}
Content-type: application/json
idempotency-key: a9c14736-2c03-4d9d-a797-3d5aa3c917d0

Request body

  • SEPA payout
  • GBP payout
  • Other currencies
{
  "amount": 12345,
  "currency": "EUR",
  "paymentTitle": "SEPA test",
  "beneficiary": {
    "name": "John Johnson",
    "iban": "DE07500105176551562526",
  }
}
{
  "amount": 12345,
  "currency": "GBP",
  "paymentTitle": "GBP test",
  "beneficiary": {
    "name": "John Johnson",
    "accountNumber": "12345678",
    "sortCode": "404777",
  }
}
{
  "amount": 12345,
  "currency": "DKK",
  "paymentTitle": "Other currency test",
  "beneficiary": {
    "name": "John Johnson",
    "iban": "DE07500105176551562526",
    "swiftBic": "BIGBPLPW",
  }
}

Fields

Field name Type Description
amount numeric 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  
   name string Full name or organisation name
   iban string Required for SEPA
   swiftBic string Optional for SEPA
   accountNumber string UK domestic payouts only
   sortCode string UK domestic payouts only

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
  • PAYOUT_CONFIRMED
  • PAYOUT_REJECTED_BY_PROVIDER

Location 

  • Sandbox
  • Production
https://api.sandbox.volt.io/payouts
https://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"
    }
  }
]

GET payout details

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

Location

  • Sandbox
  • Production
GET https://api.sandbox.volt.io/payouts/{id}
GET https://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":[]
}
  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 dispositions 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"
    }
  ]
}