Skip to main content
POST
/
v1
/
payouts
Create one or multiple payouts
curl --request POST \
  --url https://api.example.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "100.50",
  "beneficiary": {
    "id": "cc82fa1d-fc7a-478c-a734-d3bce40464e7"
  },
  "clientRef": "PAYOUT-REF-12345",
  "currency": "EUR",
  "route": "sepa_inst",
  "comment": "Monthly salary payment",
  "description": "Payment for services rendered",
  "externalSenderId": "SENDER-123",
  "inputCurrency": "EUR",
  "invoiceId": "INV-2024-001",
  "purpose": "salary",
  "quoteId": "123e4567-e89b-12d3-a456-426614174000",
  "rateId": "123e4567-e89b-12d3-a456-426614174000",
  "reference": "PAYOUT-2024-001"
}
'
{
  "amount": "100.50",
  "beneficiary": {
    "accounts": [
      {
        "createdAt": "2024-01-15T10:30:00Z",
        "currency": "EUR",
        "data": {
          "bic": "DEUTDEFF",
          "iban": "DE89370400440532013000"
        },
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "type": "iban",
        "updatedAt": "2024-01-15T10:35:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "status": "active",
    "updatedAt": "2024-01-15T10:35:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "currency": "EUR",
  "fee": "2.50",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "route": "sepa_inst",
  "status": "processing",
  "type": "fiat",
  "updatedAt": "2024-01-15T10:35:00Z",
  "balanceAfter": "98.87",
  "clientRef": "PAYOUT-REF-12345",
  "completedAt": "2024-01-15T10:40:00Z",
  "description": "Payment for services rendered",
  "failureCategory": "payment_not_approved",
  "failureReason": "Insufficient funds",
  "fxRate": "970.87378641",
  "inputAmount": "1.13",
  "inputCurrency": "EUR",
  "payoutAccountData": {
    "account": 123456789,
    "bankCode": "044",
    "crAccount": "0123456789"
  },
  "payoutAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "processedAt": "2024-01-15T10:32:00Z",
  "providerReference": "TXN123456789",
  "reference": "January invoice"
}

Documentation Index

Fetch the complete documentation index at: https://docs.zuba.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Enter Auth0 JWT token

Body

application/json

Single payout object or array of payout objects

​
amount
string
required

Amount to be paid out (as string to avoid floating-point precision issues)

Pattern: ^[0-9]+(.[0-9]{1,8})?$
Example:

"100.50"

​
beneficiary
object
required

Beneficiary information. RECOMMENDED: Reference an existing beneficiary by providing just the ID (e.g., {"id": "uuid"}). Alternatively, provide the full beneficiary object with account details to create a new one inline.

Example:
{
  "id": "cc82fa1d-fc7a-478c-a734-d3bce40464e7"
}
​
clientRef
string
required

Client reference for idempotency (max 100 characters)

Maximum string length: 100
Example:

"PAYOUT-REF-12345"

​
currency
enum<string>
required

Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
route
enum<string>
required

Payment route to use

Available options:
sepa_inst,
sepa_credit,
paysend,
bank_transfer,
ach,
fedwire
Example:

"sepa_inst"

​
comment
string

Comment for the payout

Maximum string length: 500
Example:

"Monthly salary payment"

​
description
string

Optional description of the payout (max 500 characters)

Maximum string length: 500
Example:

"Payment for services rendered"

​
externalSenderId
string

External sender ID for tracking

Maximum string length: 100
Example:

"SENDER-123"

​
inputCurrency
enum<string>

Input currency to debit from (optional). If provided, this currency will be used as the source for the payout. If not provided, the system will automatically select the currency with the largest available balance (balance minus pending transactions). Defaults to USD if no balances are found. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
invoiceId
string

Invoice ID associated with the payout

Maximum string length: 100
Example:

"INV-2024-001"

​
purpose
string

Purpose of the payout

Maximum string length: 100
Example:

"salary"

​
quoteId
string<uuid>

Cross-rate FX quote ID. Required for cross-currency payouts in supported corridors (e.g., NGN->GBP). Optional for same-currency payouts.

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
rateId
string

FX rate ID to use for conversion (optional, will use latest if not specified)

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
reference
string

Optional reference for the payout (max 140 characters)

Maximum string length: 140
Example:

"PAYOUT-2024-001"

​
senderInfo
object

Sender information (required for Paysend card payouts)

Response

Single payout created

​
amount
string
required

Amount of the payout (as string to avoid floating-point precision issues)

Example:

"100.50"

​
beneficiary
object
required

Beneficiary information

Example:
{
  "accounts": [
    {
      "createdAt": "2024-01-15T10:30:00Z",
      "currency": "EUR",
      "data": {
        "bic": "DEUTDEFF",
        "iban": "DE89370400440532013000"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "type": "iban",
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "email": "john.doe@example.com",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "status": "active",
  "updatedAt": "2024-01-15T10:35:00Z"
}
​
createdAt
string<date-time>
required

Creation timestamp

Example:

"2024-01-15T10:30:00Z"

​
currency
enum<string>
required

Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
fee
string
required

Fee charged for the payout (as string to avoid floating-point precision issues)

Example:

"2.50"

​
id
string<uuid>
required

Unique identifier for the payout

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
route
enum<string>
required

Payment route used

Available options:
sepa_inst,
sepa_credit,
paysend,
bank_transfer,
ach,
fedwire
Example:

"sepa_inst"

​
status
enum<string>
required

Current status of the payout

Available options:
created,
queued,
processing,
paid,
failed,
cancelled
Example:

"processing"

​
type
enum<string>
required

Type of payout

Available options:
fiat,
crypto
Example:

"fiat"

​
updatedAt
string<date-time>
required

Last update timestamp

Example:

"2024-01-15T10:35:00Z"

​
balanceAfter
string

Account balance after this transaction (in input currency, e.g., EUR)

Example:

"98.87"

​
clientRef
string

Client-supplied idempotency reference provided at payout creation. Stable across retries and the natural lookup key for support / reconciliation. Absent on provider-synthesized DTOs (e.g. webhook callbacks) where the original client ref is not in scope.

Maximum string length: 100
Example:

"PAYOUT-REF-12345"

​
completedAt
string<date-time>

Completion timestamp

Example:

"2024-01-15T10:40:00Z"

​
description
string

Description of the payout

Example:

"Payment for services rendered"

​
failureCategory
enum<string>

Category of failure for client-facing display

Available options:
payment_not_approved,
recipient_details,
amount_issue,
technical_error
Example:

"payment_not_approved"

​
failureReason
string

Reason for failure if payout failed

Example:

"Insufficient funds"

​
fxRate
string

FX rate applied (rate with markup charged to the client, e.g., 970.87 NGN per EUR)

Example:

"970.87378641"

​
inputAmount
string

Input amount (total amount charged to the client including fee, in input currency)

Example:

"1.13"

​
inputCurrency
enum<string>

Input currency (the currency debited from the client account). This is determined by the inputCurrency provided in the request, or automatically selected as the currency with the largest available balance, or defaults to USD. For example, EUR when paying out NGN. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
payoutAccountData
object

Payout account data (JSONB)

Example:
{
  "account": 123456789,
  "bankCode": "044",
  "crAccount": "0123456789"
}
​
payoutAccountId
string<uuid>

Payout account ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
processedAt
string<date-time>

Processing start timestamp

Example:

"2024-01-15T10:32:00Z"

​
providerReference
string

Reference from the payment provider

Example:

"TXN123456789"

​
reference
string

Optional free-text memo/narration that appears on the recipient side. Use clientRef for idempotency / support lookups.

Example:

"January invoice"