Skip to main content
POST
/
v1
/
payouts
curl -X POST "https://api.zuba.com/v1/payouts" \
  -H "Authorization: Bearer zuba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientRef": "PAYOUT-INV-001",
    "inputCurrency": "EUR",
    "amount": "1000.00",
    "currency": "EUR",
    "route": "sepa_inst",
    "beneficiary": {
      "id": "cc82fa1d-fc7a-478c-a734-d3bce40464e7"
    },
    "senderInfo": {
      "firstName": "Acme",
      "lastName": "Corp",
      "address": "123 Business Ave",
      "city": "London",
      "postalCode": "EC1A 1BB",
      "country": "GB"
    },
    "reference": "Invoice #INV-001",
    "description": "Payment for marketing services"
  }'

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "amount",
        "code": "POSITIVE_NUMBER",
        "message": "Amount must be a positive number"
      }
    ]
  }
}

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.

Create one or multiple payouts to send money to beneficiaries. This endpoint accepts either a single payout object or an array of payout objects for batch processing.

​
Request

​
clientRef
string
required
Client reference for idempotency (max 100 characters). This ensures the same payout is not created twice.
​
inputCurrency
string
Funding currency used to pay for the transaction (e.g., EUR when paying out NGN)
​
amount
string
required
The amount the beneficiary receives as a string (avoids floating-point precision issues). Must match pattern: ^[0-9]+(\.[0-9]{1,8})?$
​
currency
string
required
The currency code of value being received (ISO 4217 format, e.g., EUR, USD, GBP)
​
route
string
required
Payment route to use. Options: sepa_inst, sepa_credit, bank_transfer, ach, fedwire, paysend
​
beneficiary
object
required
RECOMMENDED: Reference an existing beneficiary by providing just the id field (e.g., {"id": "uuid"}).Inline beneficiary data is also accepted (full CreateBeneficiary payload with name, country, accounts, etc.). In that case the beneficiary is resolved idempotently: if any submitted account matches an existing active beneficiary for your client, that beneficiary is reused and no duplicate row is created. See Create Beneficiary → Idempotency.
​
reference
string
Optional payment reference (max 140 characters)
​
description
string
Optional description of the payout (max 500 characters)
​
senderInfo
object
Sender information (required for certain routes like Stripe card payouts)
​
rateId
string
FX rate ID to use for conversion (optional, will use latest if not specified)

​
Response

​
id
string
Unique identifier for the payout (UUID)
​
reference
string
Payment reference
​
description
string
Payout description
​
amount
string
The payout amount (as string)
​
currency
string
The payout currency
​
route
string
Payment route used: sepa_inst, sepa_credit, bank_transfer, ach, fedwire, paysend
​
type
string
Payout type: fiat or crypto
​
status
string
Current payout status: created, queued, processing, paid, failed, cancelled
​
beneficiary
object
Full beneficiary information (see Beneficiary DTO)
​
fee
string
Fee charged for the payout (as string)
​
failureReason
string
Reason for failure if payout failed
​
inputCurrency
string
Currency charged to the client (e.g., EUR when paying out NGN)
​
inputAmount
string
Total amount charged to client including fee (in input currency)
​
fxRate
string
FX rate applied (e.g., 1600 NGN per EUR)
​
balanceAfter
string
Account balance after this transaction (in input currency)
​
createdAt
string
ISO timestamp when the payout was created
​
updatedAt
string
ISO timestamp when the payout was last updated
​
processedAt
string
Processing start timestamp
​
completedAt
string
Completion timestamp

​
Examples

​
Using Beneficiary ID

curl -X POST "https://api.zuba.com/v1/payouts" \
  -H "Authorization: Bearer zuba_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "clientRef": "PAYOUT-INV-001",
    "inputCurrency": "EUR",
    "amount": "1000.00",
    "currency": "EUR",
    "route": "sepa_inst",
    "beneficiary": {
      "id": "cc82fa1d-fc7a-478c-a734-d3bce40464e7"
    },
    "senderInfo": {
      "firstName": "Acme",
      "lastName": "Corp",
      "address": "123 Business Ave",
      "city": "London",
      "postalCode": "EC1A 1BB",
      "country": "GB"
    },
    "reference": "Invoice #INV-001",
    "description": "Payment for marketing services"
  }'

​
Notes

​
Amount Precision

Note that amount is passed as a string (e.g., "1000.00") rather than a number. This is intentional to avoid floating-point precision issues in financial calculations.

​
Payment Routes

  • sepa_inst - SEPA Instant (usually settled within minutes)
  • sepa_credit - Standard SEPA Credit Transfer (1-2 business days)
  • paysend - Paysend (EUR, USD, GBP)
  • bank_transfer - Generic bank transfer route
  • ach - ACH transfer (USD, US domestic)
  • fedwire - Fedwire transfer (USD, US domestic, same-day settlement)

​
Error Responses

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request contains invalid parameters",
    "details": [
      {
        "field": "amount",
        "code": "POSITIVE_NUMBER",
        "message": "Amount must be a positive number"
      }
    ]
  }
}

​
Webhook Events

This endpoint triggers the following webhook events:
  • payout.created - Payout successfully created
  • payout.processing - Payout processing started
  • payout.completed - Payout successfully completed
  • payout.failed - Payout processing failed
Learn more about webhook implementation.