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

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