Home › Connect › Payouts via the API

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.

GET eligible beneficiaries

As payouts are a closed-loop system, you may only send funds to beneficiaries who you’ve received funds from through Volt Connect 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 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 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 new payout request

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

If you wish to fully automate the creation and approval of these requests, then the API requests must be signed using a private key, for more details on this please refer to here 

Location

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

Request headers

If you’re using a Volt Account as your Connect account provider, you’ll need to sign your request using an additional header.   If you’re using one of our account partners, such as Clear Junction or ISX, you don’t need to include this header. You can only test this on production, as this header is ignored on sandbox.

Find out how to sign your request

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.

Find out more about idempotency keys

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

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

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"
    }
  ]
}
← Previous Introduction to payouts
Next → Payouts via Fuzebox