Payouts

Overview

Payouts are the core functionality of the Zuba platform, enabling you to send money to beneficiaries worldwide through various payment rails including international transfers, SWIFT, US domestic rails (ACH and Fedwire), crypto networks, local bank transfers, and mobile money.

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'
  }
});

const beneficiary = await fetch('https://api.zuba.com/v1/beneficiaries', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john.doe@example.com',
    country: 'US',
    countrySubdivision: 'NY',
    address: '123 Main St',
    city: 'New York',
    postcode: '10001',
    accounts: [{
      type: 'bank_account',
      currency: 'USD',
      data: {
        accountNumber: '1234567890',
        routingNumber: '021000021',
        accountHolderName: 'John Doe',
        bankName: 'Chase Bank'
      }
    }]
  })
});

Account Types

Zuba supports multiple account types for maximum flexibility:

Bank Accounts
Crypto Wallets
Mobile Money

For the local bank rails (Nigeria, Ghana, Kenya, Uganda, Cameroon, Côte d’Ivoire), bankCode is Zuba’s internal bank identifier. Fetch the supported banks and their codes for a country from GET /v1/accounts/banks?country=<ISO-3166-1-alpha-2> (e.g. ?country=CM), which returns [{ "name", "bankCode" }] sorted by name. The list is scoped to banks Zuba can currently pay, so for Kenya it is the payable subset rather than every registered bank. Nigeria (the default) also accepts the raw CBN/NIP code directly.

EUR (IBAN)bic is optional on iban accounts.

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

GBP (IBAN)GBP beneficiaries also use the iban account type, with a GB IBAN:

{
  "type": "iban",
  "currency": "GBP",
  "data": {
    "iban": "GB29NWBK60161331926819",
    "accountHolderName": "John Smith",
    "bic": "NWBKGB2L"
  }
}

US Bank Account (USD: ACH / Domestic Wire)

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

Nigerian Bank AccountbankCode accepts the 3-digit CBN short code (e.g. 044) or the 6-digit NIP long code (e.g. 000014); crAccount is the 10-digit account number.

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

Ghanaian Bank AccountbankCode is Zuba’s internal Ghana bank identifier (e.g. gh_0001); crAccount is the 8–20 digit account number.

{
  "type": "bank_account",
  "currency": "GHS",
  "data": {
    "bankCode": "gh_0002",
    "crAccount": "12223444555"
  }
}

Kenyan Bank AccountbankCode is Zuba’s internal Kenya bank identifier (e.g. ke_0001 for KCB, ke_0003 for Absa); crAccount is the 5–20 digit account number. KES is dual-rail — the same currency also pays out to a mobile money wallet (see the Mobile Money tab).

{
  "type": "bank_account",
  "currency": "KES",
  "data": {
    "bankCode": "ke_0001",
    "crAccount": "1000012345"
  }
}

Cameroonian Bank AccountbankCode is Zuba’s internal Cameroon bank identifier (e.g. cm_0001 for Afriland First Bank, cm_0006 for BGFIBANK); crAccount is the 8–24 digit account number. XAF is dual-rail — the same currency also pays out to a mobile money wallet (see the Mobile Money tab).

{
  "type": "bank_account",
  "currency": "XAF",
  "data": {
    "bankCode": "cm_0006",
    "crAccount": "10005000123456"
  }
}

XAF bank payouts additionally require the sender’s KYC. An individual sender must supply, in senderInfo: firstName and lastName, phoneNumber in international format, fundOrigin (SALARY, BUSINESS, or INVESTMENT), and gender (M or F), or the payout is rejected at creation. To send as your own workspace, omit senderInfo entirely — your account is then used as the business originator. Supply senderInfo only to pay out on behalf of a distinct third party; a business third-party sender must include companyName, registrationNumber, and country (its jurisdiction of incorporation).

XAF Bank Payout (Cameroon)

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-BANK-XAF-001',
    amount: '50000',
    currency: 'XAF',
    route: 'bank_transfer',
    beneficiary: { id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
    senderInfo: {
      type: 'individual',
      firstName: 'Jane',
      lastName: 'Doe',
      phoneNumber: '+237655555555',
      fundOrigin: 'SALARY',
      gender: 'F'
    },
    reference: 'Supplier payment'
  })
});

Ivorian Bank AccountbankCode is Zuba’s internal Côte d’Ivoire bank identifier (e.g. ci_0009 for Ecobank, ci_0013 for Société Générale); crAccount is the 8–24 digit account number. XOF is dual-rail — the same currency also pays out to a mobile money wallet (see the Mobile Money tab), and the bank rail serves Côte d’Ivoire only.

{
  "type": "bank_account",
  "currency": "XOF",
  "data": {
    "bankCode": "ci_0013",
    "crAccount": "000100123456789"
  }
}

The per-transaction amount is XOF 200–2,000,000.Côte d’Ivoire bank payouts use the sender’s name. Supply firstName and lastName in senderInfo for an individual sender (or companyName for a business sender). If senderInfo is omitted, your workspace’s legal name is used as the originator’s first and last name instead. Unlike Cameroon, Côte d’Ivoire does not need phoneNumber, fundOrigin, or gender.Ugandan Bank AccountbankCode is Zuba’s internal Uganda bank identifier (e.g. ug_0020 for Stanbic, ug_0002 for Absa); crAccount is the 5–20 digit account number. UGX is dual-rail — the same currency also pays out to a mobile money wallet (see the Mobile Money tab). The Ugandan shilling has no minor unit, so amount must be a whole number on both rails.

{
  "type": "bank_account",
  "currency": "UGX",
  "data": {
    "bankCode": "ug_0020",
    "crAccount": "1002003004"
  }
}

The per-transaction minimum is UGX 1, with no published ceiling.

UGX bank payouts are in early access — a gated corridor. An unpinned workspace’s UGX bank payout is rejected at creation with RAIL_UNAVAILABLE. UGX mobile money is gated on the same corridor. Enablement can be granted per rail, so ask your account manager for the rails you need.

Sandbox-only currencies

ZMW (Zambian kwacha), MZN (Mozambican metical), MWK (Malawian kwacha) and EGP (Egyptian pound) are available in the sandbox only. Payouts to them settle with simulated outcomes. See Sandbox testing. In production these currencies are not yet available and a payout to one is rejected at creation.

Zambian Bank Account (sandbox only)

{
  "type": "bank_account",
  "currency": "ZMW",
  "data": {
    "bankCode": "260001",
    "accountNumber": "1234567890",
    "accountHolderName": "Chanda Mwansa"
  }
}

The same shape applies for MZN, MWK, and EGP: any bankCode is accepted in the sandbox.

Stablecoin payouts support USDC and USDT on Ethereum (ERC-20) and Solana (SPL), and USDT on Tron (TRC-20). USDC is not available on Tron. accountHolderName is required on wallet accounts.USDT on Tron (TRC-20)

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

USDC on Solana (SPL)

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

USDT on Solana (SPL)

{
  "type": "wallet",
  "currency": "USDT",
  "data": {
    "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "network": "SOLANA",
    "accountHolderName": "John Doe"
  }
}

USDC on Ethereum (ERC-20)

{
  "type": "wallet",
  "currency": "USDC",
  "data": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "network": "ETHEREUM",
    "accountHolderName": "John Doe"
  }
}

USDT on Ethereum (ERC-20)

{
  "type": "wallet",
  "currency": "USDT",
  "data": {
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "network": "ETHEREUM",
    "accountHolderName": "John Doe"
  }
}

Mobile money pays out to a beneficiary’s mobile money wallet in XOF (West African CFA franc), XAF (Central African CFA franc), GHS (Ghana cedi), KES (Kenyan shilling), or UGX (Ugandan shilling).

UGX mobile money is in early access, gated on the same corridor as the UGX bank rail; an unpinned workspace is rejected at creation with RAIL_UNAVAILABLE. Enablement can be granted per rail, so ask your account manager for the rails you need. XOF, XAF, GHS and KES mobile money are open.

XOF (West Africa)

{
  "type": "mobile",
  "currency": "XOF",
  "data": {
    "mobileProvider": "orange",
    "phoneNumber": "+2250123456789",
    "country": "CI"
  }
}

XAF (Cameroon)

{
  "type": "mobile",
  "currency": "XAF",
  "data": {
    "mobileProvider": "mtn",
    "phoneNumber": "+237650000000",
    "country": "CM"
  }
}

GHS (Ghana)

{
  "type": "mobile",
  "currency": "GHS",
  "data": {
    "mobileProvider": "mtn",
    "phoneNumber": "+233241234567",
    "country": "GH"
  }
}

KES (Kenya)

{
  "type": "mobile",
  "currency": "KES",
  "data": {
    "mobileProvider": "safaricom",
    "phoneNumber": "+254712345678",
    "country": "KE"
  }
}

UGX (Uganda)

{
  "type": "mobile",
  "currency": "UGX",
  "data": {
    "mobileProvider": "mtn",
    "phoneNumber": "+256772123456",
    "country": "UG"
  }
}

phoneNumber must be in international format (including the +). mobileProvider must be valid for country:

Country	`currency`	`country`	`mobileProvider`
Côte d’Ivoire	`XOF`	`CI`	`orange`, `mtn`, `moov`, `wave`
Senegal	`XOF`	`SN`	`orange`, `free`, `wave`
Mali	`XOF`	`ML`	`orange`, `moov`, `wave`
Burkina Faso	`XOF`	`BF`	`orange`, `moov`, `wave`
Benin	`XOF`	`BJ`	`mtn`, `moov`
Togo	`XOF`	`TG`	`moov`, `tmoney`
Cameroon	`XAF`	`CM`	`mtn`, `orange`
Ghana	`GHS`	`GH`	`mtn`, `vodafone`, `airteltigo`
Kenya	`KES`	`KE`	`safaricom` (or `mpesa`), `airtel`, `equitel`
Uganda	`UGX`	`UG`	`mtn` (or `momo`), `airtel`

Pay out with route: "mobile_money". See Mobile money below for amount limits, sender requirements, and the dual-rail currencies (GHS, KES, UGX).

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'
  })
});

senderInfo is optional. When omitted, your workspace is used as the business originator. Some corridors require it: GHS mobile money needs the sender’s first and last name, and XAF mobile money needs the sender’s name and phone number.

Batch Payouts

Process multiple payouts in a single API call. Every payout in the batch is validated independently and requires its own route:

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: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
      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'
      },
      reference: 'Salary March 2024'
    },
    {
      clientRef: 'PAYOUT-BATCH-002',
      beneficiary: { id: '123e4567-e89b-12d3-a456-426614174000' },
      amount: '1500.00',
      inputCurrency: 'EUR',
      currency: 'USD',
      route: 'ach',
      reference: 'Freelancer payment'
    }
  ])
});

Sending from a sub-account

If your workspace has sub-accounts, pass the sub-account’s ID in the optional Zuba-Account-Id header on POST /v1/payouts to send the payout from that sub-account’s balance: the amount and fee are debited from the sub-account, and the payout records which sub-account it belongs to. Omit the header to send from your master (workspace) balance, exactly as the examples above. The named sub-account must be one you own and must be active. A header naming an account you do not own is rejected with 403 not_account_owner, and a sub-account that is not yet active is rejected with 422 ACCOUNT_NOT_ACTIVE. Sub-accounts are a gated feature — contact your account manager to enable them.

Payment Routes

Select the rail with the route field on each payout request:

Route	Regions	Speed
`bank_transfer`	Local bank rails: Nigeria (NGN), Ghana (GHS), Kenya (KES), Uganda (UGX), Cameroon (XAF), Côte d’Ivoire (XOF)	Minutes to 1 business day
`ach`	United States	1-3 business days
`fedwire`	United States (domestic wire)	Same business day
`swift`	International (availability varies by destination country)	1-3 business days
`crypto`	On-chain (Ethereum, Solana, Tron)	Minutes (network-dependent)
`mobile_money`	West Africa (XOF: CI, SN, ML, BF, BJ, TG), Central Africa (XAF: Cameroon), Ghana (GHS), Kenya (KES), and Uganda (UGX)	Minutes

EUR and GBP payouts are delivered to IBAN accounts over Zuba’s international transfer network. The rail is selected automatically from the beneficiary’s iban account and surfaces as international on payout reads and in the dashboard. The former sepa_credit / sepa_inst route values have been retired and are no longer routable.

Crypto rail

Set route: "crypto" to send a stablecoin (USDC or USDT) on-chain to a crypto wallet beneficiary. The currency is the stablecoin and is debited from your same-currency balance (no FX). The destination network and address come from the beneficiary’s wallet account (see Crypto Wallets above), so the request only references the beneficiary by id:

Crypto Payout

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-CRYPTO-001',
    amount: '250.00',
    currency: 'USDC',
    route: 'crypto',
    beneficiary: { id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
    reference: 'Contractor payment'
  })
});

The funds are held the moment the payout is created, screened for compliance, then signed and broadcast on-chain. The payout reaches paid only once the transaction has broadcast; if it is declined or signing fails, the held funds are returned to your balance automatically. Crypto payouts are availability-gated per environment. Contact your account manager to enable them. Once the transfer is broadcast, GET /v1/payouts/{id} returns the on-chain transaction hash in the txHash field (null for non-crypto payouts or before broadcast). Use it to look the transfer up on a block explorer for the payout’s network.

Mobile money (XOF, XAF, GHS, KES, and UGX)

Set route: "mobile_money" to pay out XOF to a beneficiary’s mobile money wallet across West Africa, XAF to a wallet in Cameroon, GHS to a wallet in Ghana, KES to a wallet in Kenya, or UGX to a wallet in Uganda. The destination provider and phone number come from the beneficiary’s mobile account (see Mobile Money under Account Types above):

Mobile Money Payout

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-MM-001',
    amount: '5000',
    currency: 'XOF',
    route: 'mobile_money',
    beneficiary: { id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
    reference: 'Supplier payment'
  })
});

Supported in Côte d’Ivoire, Senegal, Mali, Burkina Faso, Benin, and Togo (XOF), Cameroon (XAF), Ghana (GHS), Kenya (KES), and Uganda (UGX). The per-transaction amount depends on the destination currency: XOF 200–2,000,000, XAF 500–1,000,000, GHS 5–25,000, KES 1–250,000, UGX 1–5,000,000. A mismatched provider/country, an invalid phone number, an unsupported country, a currency that isn’t XOF/XAF/GHS/KES/UGX, or an out-of-range amount is rejected at creation. UGX amounts must be whole numbers. The Ugandan shilling has no minor unit, so a fractional amount is rejected at creation on both the mobile and bank rails. Ghana (GHS), Kenya (KES), Uganda (UGX), Cameroon (XAF), and Côte d’Ivoire (XOF) are dual-rail. The same currency also pays out over a bank account (route: "bank_transfer"); the rail is chosen by the beneficiary’s account type (mobile vs bank_account). XOF mobile money covers six West African countries but the XOF bank rail serves Côte d’Ivoire only. XAF bank payouts carry extra sender KYC (fundOrigin and gender) — see the Bank Account tab. GHS mobile requires the sender’s first and last name via senderInfo (no phone, unlike Cameroon), or the payout is rejected:

GHS Mobile Money Payout (Ghana)

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-MM-GHS-001',
    amount: '100',
    currency: 'GHS',
    route: 'mobile_money',
    beneficiary: { id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
    senderInfo: {
      type: 'individual',
      firstName: 'Ama',
      lastName: 'Owusu'
    },
    reference: 'Supplier payment'
  })
});

Kenya (KES) and Uganda (UGX) need no senderInfo. Uganda is in early access on either rail — see the gate note under Mobile Money in Beneficiary account types. Supply the beneficiary and amount only:

KES Mobile Money Payout (Kenya)

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-MM-KES-001',
    amount: '5000',
    currency: 'KES',
    route: 'mobile_money',
    beneficiary: { id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
    reference: 'Supplier payment'
  })
});

The same shape applies to Uganda, with a whole-number amount:

UGX Mobile Money Payout (Uganda)

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-MM-UGX-001',
    amount: '10000',
    currency: 'UGX',
    route: 'mobile_money',
    beneficiary: { id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
    reference: 'Supplier payment'
  })
});

Cameroon (XAF) additionally requires sender details. Supply the originator’s name and phone in senderInfo, or the payout is rejected:

XAF Mobile Money Payout (Cameroon)

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-MM-XAF-001',
    amount: '2000',
    currency: 'XAF',
    route: 'mobile_money',
    beneficiary: { id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7' },
    senderInfo: {
      type: 'individual',
      firstName: 'Jane',
      lastName: 'Doe',
      phoneNumber: '+237655555555'
    },
    reference: 'Supplier payment'
  })
});

XOF, XAF, GHS and KES mobile money are open. UGX is in early access on both rails, and an unpinned workspace is rejected at creation with RAIL_UNAVAILABLE. Enablement can be granted per rail, so ask your account manager for the rails you need.

USD rails

For USD payouts, three rails are surfaced by GET /v1/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. Destination coverage spans most major markets and expands as corridors are enabled, so it is not a fixed list: GET /v1/payouts/available-rails?accountId=<uuid> reports, per saved account, whether SWIFT currently serves that account’s destination country (available plus an unavailableReason when it does not).

Over the API you pass route on every payout request; the beneficiary account just has to match it: a swift account for route "swift", a US bank_account for "ach" / "fedwire". In the dashboard, the rail chosen when the account was saved is remembered so senders aren’t re-prompted. Beneficiary accounts intended for SWIFT must be created with type: "swift" and supply swiftCode, accountNumber, beneficiaryCountry, and (optionally) bankName / beneficiaryAddress in data. SWIFT payouts also require a purpose-of-payment document: request an upload URL from POST /v1/payouts/pop-documents/upload-url, upload the document, and pass the returned key as purposeOfPaymentDocumentKey on the payout. A SWIFT payout without it is rejected at creation. A SWIFT payout from a non-USD balance (e.g. NGN) is a cross-rate send: it passes through a quote (POST /v1/quotes), is debited in the source currency, and Zuba funds the USD outflow to the destination bank. A same-currency USD→USD SWIFT payout needs no quote and is sent 1:1 from your USD balance.

Route Selection Logic

The rail is determined by the beneficiary’s account type and currency:

Tracking & Status

Payout Statuses

Status	Description	Next Actions
`created`	Payout has been created	Can be cancelled
`queued`	Queued for processing	Can be cancelled; 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

From the dashboard, a receipt can be downloaded for a payout in any status except cancelled. For a payout that is still in progress, the receipt reflects its current status.

Amounts above corridor limits

Every corridor has an amount cap, and a payout or payout quote above it is rejected by the standard bounds checks. Amounts above corridor limits are served by the orders channel (POST /v1/orders) for order-enabled accounts: a quote-first flow where funds are held from your balance and the trade is executed by Zuba’s desk within a stated execution window. See the Trade Desk Orders guide or contact us to enable orders on your account.

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

curl "https://api.zuba.com/v1/payouts/123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_API_KEY"

Best Practices

Beneficiary Validation

Always validate beneficiary details before creating
Use GET /v1/payouts/requirements to check the beneficiary fields required for a currency before submitting
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

Get Started

Core Concepts

Guides

Overview

Payout Lifecycle

Beneficiaries & Accounts

Beneficiary Management

Account Types

Creating Payouts

Single Payout

Batch Payouts

Sending from a sub-account

Payment Routes

Crypto rail

Mobile money (XOF, XAF, GHS, KES, and UGX)

USD rails

Route Selection Logic

Tracking & Status

Payout Statuses

Amounts above corridor limits

Real-time Tracking

Best Practices

Next Steps

First Payout Guide

Batch Processing

Webhooks

API Reference

​Overview

​Payout Lifecycle

​Beneficiaries & Accounts

​Beneficiary Management

​Account Types

​Creating Payouts

​Single Payout

​Batch Payouts

​Sending from a sub-account

​Payment Routes

​Crypto rail

​Mobile money (XOF, XAF, GHS, KES, and UGX)

​USD rails

​Route Selection Logic

​Tracking & Status

​Payout Statuses

​Amounts above corridor limits

​Real-time Tracking

​Best Practices

​Next Steps

First Payout Guide

Batch Processing

Webhooks

API Reference

Overview

Payout Lifecycle

Beneficiaries & Accounts

Beneficiary Management

Account Types

Creating Payouts

Single Payout

Batch Payouts

Sending from a sub-account

Payment Routes

Crypto rail

Mobile money (XOF, XAF, GHS, KES, and UGX)

USD rails

Route Selection Logic

Tracking & Status

Payout Statuses

Amounts above corridor limits

Real-time Tracking

Best Practices

Next Steps