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 Ghana, Kenya, Uganda, Cameroon and Côte d’Ivoire, bankCode is Zuba’s internal bank identifier. Fetch the supported banks and their codes for a country from GET /v1/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 and Uganda it is the payable subset rather than every registered bank. For Nigeria, the default when country is omitted, bankCode is the CBN short code or the NIP long code, and a beneficiary account accepts either.

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 payouts require the sender’s KYC on both rails. An individual sender must supply, in senderInfo: firstName and lastName, phoneNumber in international format, fundOrigin (SALARY, BUSINESS, or INVESTMENT), gender (M or F), and country (the sender’s own country as an ISO 3166-1 alpha-2 code), or the payout is rejected at creation. The same set applies to XAF mobile money — see the Mobile Money tab. 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',
      country: 'CM'
    },
    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.

Argentine Bank Account (ARS)

ARS payouts are in beta — a gated corridor. Contact your account manager to have it enabled for your workspace; until it is, a payout to ARS is rejected at creation.

An Argentine beneficiary is identified by a single account string plus the kind of identifier it is. accountNumber, accountType and accountHolderName are all required. accountType is not inferred: a CBU and a CVU are both 22 digits and cannot be told apart by shape.

`accountType`	What it is	Format
`CBU`	Clave Bancaria Uniforme — a bank account at a traditional bank	22 digits
`CVU`	Clave Virtual Uniforme — an account at a digital wallet or fintech	22 digits
`ALIAS`	A human-readable alias registered against a CBU or CVU	Alphanumeric, dot-separated

{
  "type": "bank_account",
  "currency": "ARS",
  "data": {
    "accountNumber": "0290013110000576749489",
    "accountType": "CBU",
    "accountHolderName": "María González"
  }
}

ARS payouts additionally require the sender’s identity. Supply, in senderInfo: firstName, lastName, and dateOfBirth (YYYY-MM-DD). This is required whether you are paying as your own workspace or on behalf of a third party.

ARS Bank Payout (Argentina)

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-ARS-001',
    amount: '150000.00',
    currency: 'ARS',
    route: 'bank_transfer',
    beneficiary: { id: 'f1b9c2a4-8e7d-4a3b-9c15-2d6e8f0a4b71' },
    senderInfo: {
      type: 'individual',
      firstName: 'Jane',
      lastName: 'Doe',
      dateOfBirth: '1990-01-01'
    },
    reference: 'Supplier payment'
  })
});

Sandbox-only currencies

ZMW (Zambian kwacha), 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.MZN (Mozambican metical) is simulated in the sandbox too, over mobile money rather than a bank account. See Mozambique (MZN) mobile money. In production an MZN payout is rejected at creation unless your workspace has been enabled for it.

Zambian Bank Account (sandbox only)

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

The same shape applies for 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.Individual beneficiaries need a date of birth. In production a crypto payout to an individual beneficiary is screened under the Travel Rule, whatever the amount, and the beneficiary must carry dateOfBirth (YYYY-MM-DD). type defaults to individual, so a beneficiary created without one is screened as an individual. Set the date of birth when you create the beneficiary, or add it to a saved one with PUT /v1/beneficiaries/{id}. A business beneficiary needs no date of birth. See Travel Rule for what is checked when.Individual beneficiary with a USDC wallet on Solana

{
  "name": "John Doe",
  "type": "individual",
  "country": "US",
  "dateOfBirth": "1985-05-20",
  "accounts": [{
    "type": "wallet",
    "currency": "USDC",
    "data": {
      "address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
      "network": "SOLANA",
      "accountHolderName": "John Doe"
    }
  }]
}

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. On a crypto payout an individual sender must also carry dateOfBirth; see Travel Rule.

When a quote is required

A quote (POST /v1/quotes, passed as quoteId) is required only for payouts funded from an NGN balance into USD, EUR or GBP. On every other pair a quoteId is optional: pass one to lock the rate for the payout, or omit it and the payout is priced at the current rate. A cross-currency payout on a pair listed by GET /v1/fx/cross-rate-quotes/corridors goes out only where your pricing policy covers it; a listed pair nothing prices is rejected with CORRIDOR_NOT_ENABLED, with or without a quote. On such a pair the amount must also sit inside that corridor’s per-transaction band, or the payout is rejected with AMOUNT_OUT_OF_BOUNDS. Same-currency payouts carry no band on the payout path. A cross-currency pair the listing has never carried, such as sends into NGN, is priced at the current rate whether or not your policy prices it; a pair the listing carries for other clients but not for you is one your policy does not cover, and is refused. A pair whose stored rate is zero or negative is rejected with INSUFFICIENT_LIQUIDITY; a pair with no stored rate at all, or whose rate has expired, is rejected with a 400 carrying the message FX rate not available for <source> to <destination> conversion and no error code.

Sending without a quoteId removes the quote’s single-use protection: one quote can fund at most one payout, so a retried request carrying the same quoteId cannot pay twice. On a payout sent without one, that guard is the Idempotency-Key header. Send an Idempotency-Key on any request you might retry, including a retry after a timeout where you never saw the response.

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), Argentina (ARS — beta, see Account Types)	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.

Travel Rule

In production every crypto payout is screened under the Travel Rule, whatever the amount, so both parties must be identifiable. Omit senderInfo and your workspace is the business originator, which needs nothing more. Otherwise:

Party	Required	Checked
`individual` beneficiary (the default `type`)	`dateOfBirth` on the beneficiary	At `POST /v1/payouts`: refused with `400`, no payout is created and no funds are held
Individual sender (`senderInfo` with `type: "individual"`, the default)	`firstName`, `lastName` and `dateOfBirth` in `senderInfo`	After creation: the payout is created and its funds held, then it fails, the hold is returned and `payout.failed` fires
`business` beneficiary or business sender	No date of birth (a `dateOfBirth` on a business sender is refused with `SENDER_INFO_INVALID`)	—

The beneficiary refusal is a 400 whose message names dateOfBirth and carries no code. Add the date of birth with PUT /v1/beneficiaries/{id} and resubmit. The sandbox does not run Travel Rule screening, so a crypto payout that succeeds there without a date of birth is refused in production.

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 payouts carry extra sender KYC on both rails (fundOrigin, gender, and country) — 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 the sender’s KYC. An individual sender must supply firstName, lastName, phoneNumber, fundOrigin, gender, and country in senderInfo — the same set the bank rail requires — or the payout is rejected at creation:

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',
      fundOrigin: 'SALARY',
      gender: 'F',
      country: 'CM'
    },
    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 funded from an NGN balance 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

Cancelling a payout

POST /v1/payouts/{id}/cancel cancels a payout that is still created or queued. The balance debited at creation (principal, fee and any conversion legs) is returned to the account it was taken from, and a payout.cancelled webhook is delivered. Retrying a cancel is always safe: an already-cancelled payout is returned again, and a balance return that had not completed is driven to completion. If the balance return does not complete, the call responds 500 INTERNAL_ERROR while the payout is already cancelled; the payout is flagged for our operators and a later cancel call completes the return. A payout in any status other than created, queued or cancelled is refused with 409 PAYOUT_NOT_CANCELLABLE; check its status with GET /v1/payouts/{id} instead. 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 a per-transaction band, and a payout or payout quote outside 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

When a quote is required

Batch Payouts

Sending from a sub-account

Payment Routes

Crypto rail

Travel Rule

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

USD rails

Route Selection Logic

Tracking & Status

Payout Statuses

Cancelling a payout

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

​When a quote is required

​Batch Payouts

​Sending from a sub-account

​Payment Routes

​Crypto rail

​Travel Rule

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

​USD rails

​Route Selection Logic

​Tracking & Status

​Payout Statuses

​Cancelling a payout

​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

When a quote is required

Batch Payouts

Sending from a sub-account

Payment Routes

Crypto rail

Travel Rule

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

USD rails

Route Selection Logic

Tracking & Status

Payout Statuses

Cancelling a payout

Amounts above corridor limits

Real-time Tracking

Best Practices

Next Steps