Payouts - Zuba

Overview

Payouts are the core functionality of the Zuba platform, enabling you to send money to beneficiaries worldwide through various payment rails including SEPA, SWIFT, crypto networks, and local payment methods.

Payout Lifecycle

Beneficiaries & Accounts

Beneficiary Management

Before sending payouts, you must create beneficiaries with their payment details:

const beneficiary = await fetch(`https://api.zuba.com/v1/beneficiaries/${beneficiaryId}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

Account Types

Zuba supports multiple account types for maximum flexibility:

Bank Accounts
Crypto Wallets
Card Payouts

SEPA (European Union)

{
  "type": "iban",
  "currency": "EUR",
  "data": {
    "iban": "DE89370400440532013000",
    "accountHolderName": "John Doe",
    "bic": "DEUTDEFF"
  }
}

US ACH

{
  "type": "bank_account",
  "currency": "USD",
  "data": {
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "accountHolderName": "John Doe",
    "bankName": "Chase Bank"
  }
}

UK Bank Account

{
  "type": "bank_account",
  "currency": "GBP",
  "data": {
    "accountNumber": "12345678",
    "sortCode": "123456",
    "accountHolderName": "John Smith",
    "bankName": "Barclays"
  }
}

Nigerian Bank Account

{
  "type": "bank_account",
  "currency": "NGN",
  "data": {
    "bankCode": "044",
    "crAccount": "1234567890",
  }
}

USDT on Tron (TRC-20)

{
  "type": "wallet",
  "currency": "USDT",
  "data": {
    "address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
    "network": "TRON"
  }
}

USDC on Solana (SPL)

{
  "type": "wallet",
  "currency": "USDC",
  "data": {
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "network": "SOLANA"
  }
}

USDC on Ethereum (ERC-20)

{
  "type": "wallet",
  "currency": "USDC",
  "data": {
    "address": "0x742d35Cc6634C0532925a3b8D33AA5e0000000000",
    "network": "ETHEREUM"
  }
}

USDT on Ethereum (ERC-20)

{
  "type": "wallet",
  "currency": "USDT",
  "data": {
    "address": "0x742d35Cc6634C0532925a3b8D33AA5e0000000000",
    "network": "ETHEREUM"
  }
}

Debit/Credit Card

{
  "type": "card",
  "currency": "EUR",
  "data": {
    "cardNumber": "4242424242424242",
    "accountHolderName": "John Doe"
  }
}

Creating Payouts

Single Payout

After creating a beneficiary, use their ID to create payouts (recommended approach). Currency Fields: inputCurrency is the currency from your account you’ll be paying from, while currency is what the beneficiary will receive (automatic conversion if different):

const payout = await fetch('https://api.zuba.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientRef: 'PAYOUT-INV-001',
    amount: '1000.00',
    inputCurrency: 'EUR',
    currency: 'NGN',
    route: 'bank_transfer',
    senderInfo: {
      firstName: 'Jack',
      lastName: 'Jones',
      address: '456 London Road',
      city: 'London',
      postalCode: 'SW1A 1AA',
      country: 'GB',
      dateOfBirth: '1985-06-15'
    },
    beneficiary: {
      id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7'
    },
    reference: 'Invoice #INV-001',
    description: 'Payment for marketing services'
  })
});

Batch Payouts

Process multiple payouts in a single API call for efficiency:

const payouts = await fetch('https://api.zuba.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      clientRef: 'PAYOUT-BATCH-001',
      beneficiary: { id: 'ben_1234567890' },
      amount: '1000.00',
      inputCurrency: 'EUR',
      currency: 'EUR',
      senderInfo: {
        firstName: 'Jack',
        lastName: 'Jones',
        address: '456 London Road',
        city: 'London',
        postalCode: 'SW1A 1AA',
        country: 'GB',
        dateOfBirth: '1985-06-15'
      },
      reference: 'Salary March 2024'
    },
    {
      clientRef: 'PAYOUT-BATCH-002',
      beneficiary: { id: 'ben_0987654321' },
      amount: '1500.00',
      inputCurrency: 'EUR',
      currency: 'USD',
      senderInfo: {
        firstName: 'Jack',
        lastName: 'Jones',
        address: '456 London Road',
        city: 'London',
        postalCode: 'SW1A 1AA',
        country: 'GB',
        dateOfBirth: '1985-06-15'
      },
      reference: 'Freelancer payment'
    }
  ])
});

Payment Routes

Zuba automatically selects the optimal payment route, but you can specify preferences:

Route	Regions	Speed
`sepa_credit`	European Union	1-2 business days
`sepa_inst`	EU (SEPA Instant banks)	< 10 seconds
`bank_transfer`	Multiple regions	Varies by destination
`ach`	United States	1-3 business days
`fedwire`	United States (domestic wire)	Same business day
`swift`	International (10 supported countries)	1-3 business days

USD rails

For USD payouts, three rails are surfaced by GET /payouts/available-rails?accountId=<uuid>:

fedwire — domestic wire to a US bank. Requires routing + account number on the beneficiary.
ach — batched same-day-to-3-day transfer to a US bank. Same required fields as fedwire.
swift — international wire via SWIFT. Requires BIC + IBAN/account number + the beneficiary’s bank country. Currently supported destinations: AU, BM, BR, CA, DE, FR, GB, HK, NL, PT.

The rail is fixed at beneficiary-account creation time via the route field stored on the account, so payouts against an existing account don’t re-prompt the sender to pick a method. New beneficiary accounts intended for SWIFT must be created with type: "swift" and supply swiftCode, accountNumber, beneficiaryCountry, and (optionally) bankName / beneficiaryAddress in data. SWIFT payouts always pass through a cross-rate quote (POST /quotes/cross-rate) — the sender is debited in their source currency (e.g. NGN) and Zuba satisfies the USD outflow from a pre-funded pool on the destination bank.

Route Selection Logic

Tracking & Status

Payout Statuses

Status	Description	Next Actions
`created`	Payout has been created	Can be cancelled
`queued`	Queued for processing	Monitor for updates
`processing`	Being processed by payment provider	Monitor for updates
`paid`	Successfully delivered to beneficiary	Download receipt
`failed`	Processing failed	Review error, retry
`cancelled`	Cancelled by user or system	Funds returned

Real-time Tracking

const payout = await fetch(`https://api.zuba.com/v1/payouts/${payoutId}`, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await payout.json();
console.log(data.status); // created, queued, processing, paid, failed, cancelled

Best Practices

Beneficiary Validation

Always validate beneficiary details before creating
Use SEPA reachability check for EU transactions
Store beneficiary IDs for repeat payments
Keep beneficiary information up to date

Error Handling

Implement proper error handling for all API calls
Use exponential backoff for retries
Monitor webhook notifications for status updates
Log all transactions for audit purposes

Security

Never expose API keys in client-side code
Validate webhook signatures
Use HTTPS for all API communications
Implement proper access controls

Next Steps

First Payout Guide

Step-by-step guide to send your first payout

Batch Processing

Learn how to process multiple payouts efficiently

Webhooks

Set up real-time notifications for payout status

API Reference

Complete API documentation for payouts

Documentation Index

​Overview

​Payout Lifecycle

​Beneficiaries & Accounts

​Beneficiary Management

​Account Types

​Creating Payouts

​Single Payout

​Batch Payouts

​Payment Routes

​USD rails

​Route Selection Logic

​Tracking & Status

​Payout Statuses

​Real-time Tracking

​Best Practices

​Next Steps