Your First Payout

This guide walks you through creating and sending your first payout with the Zuba API. You’ll create a beneficiary with a Nigerian bank account, then pay them NGN from your EUR balance; the currency conversion happens automatically.

Prerequisites

Before you start, make sure you have:

Valid API credentials (see Authentication)
Your API base URL
A Sandbox or production account with sufficient balance

Step 1: Create a Beneficiary

First, create a beneficiary to receive the payout. A beneficiary represents a person or entity together with their payment account details. For NGN bank accounts, bankCode is the 3-digit CBN short code (e.g. 044) or the 6-digit NIP long code (e.g. 000014), and crAccount is the 10-digit account number.

const beneficiaryData = {
  name: "Adaeze Obi",
  email: "adaeze.obi@example.com",
  country: "NG",
  address: "12 Marina Road",
  city: "Lagos",
  postcode: "101233",
  accounts: [
    {
      type: "bank_account",
      currency: "NGN",
      data: {
        bankCode: "044",
        crAccount: "1234567890"
      }
    }
  ]
};

const response = await fetch('https://api.sandbox.zuba.com/v1/beneficiaries', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify(beneficiaryData)
});

const beneficiary = await response.json();
console.log('Beneficiary created:', beneficiary.id);

string

Unique UUID for the created beneficiary

array

Array of payment accounts with their IDs and details

Required beneficiary fields vary by destination currency and by whether the recipient is an individual or a business. Call GET /v1/payouts/requirements?currency=USD&route=swift before submitting to see exactly which fields the corridor needs of the recipient and of the sender, for an individual and for a business of each, instead of discovering them through validation errors.The response also lists rules a field value must satisfy, as a pattern to test before submitting: a corridor that addresses an individual recipient by first and last name separately reports one for name, and refuses a single-token name with a 400 naming name.A business recipient is its legal name and needs no split.

Step 2: Create Your First Payout

Now create a payout to your beneficiary. RECOMMENDED: Reference the beneficiary by ID (from Step 1). Currency Fields: inputCurrency is the currency debited from your account, while currency is what the beneficiary receives. When they differ, Zuba converts automatically; no separate quote is needed for this corridor:

const payoutData = {
  clientRef: "PAYOUT-0001",
  amount: "80000.00",
  inputCurrency: "EUR",
  currency: "NGN",
  route: "bank_transfer",
  beneficiary: {
    id: beneficiary.id // Reference the beneficiary created in Step 1
  },
  reference: "Invoice payment",
  description: "Services rendered"
};

const payoutResponse = await fetch('https://api.sandbox.zuba.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify(payoutData)
});

const payout = await payoutResponse.json();
console.log('Payout created:', payout.id);

senderInfo is optional. If omitted, the originator is the paying account as its KYB application was approved: your workspace, or the sub-account named in Zuba-Account-Id. Supply it only when paying out on behalf of a distinct third party. Some corridors, such as mobile money in Ghana and Cameroon, require it.

Alternatively, provide the full beneficiary object to create a new beneficiary inline:

const payoutData = {
  clientRef: "PAYOUT-0001",
  amount: "80000.00",
  inputCurrency: "EUR",
  currency: "NGN",
  route: "bank_transfer",
  beneficiary: {
    name: "Adaeze Obi",
    email: "adaeze.obi@example.com",
    country: "NG",
    accounts: [{
      type: "bank_account",
      currency: "NGN",
      data: {
        bankCode: "044",
        crAccount: "1234567890"
      }
    }]
  },
  reference: "Invoice payment",
  description: "Services rendered"
};

See Payment Routes for available routes and their characteristics.

Step 3: Monitor Payout Status

Track your payout’s progress by checking its status:

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

const payoutDetails = await statusResponse.json();
console.log('Status:', payoutDetails.status);

A fresh payout moves through created → queued → processing → paid, so don’t be surprised to see created or queued if you poll immediately after creation. See Payout Statuses for detailed status definitions.

Step 4: Handle the Response

A successful payout response includes:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "clientRef": "PAYOUT-0001",
  "reference": "Invoice payment",
  "description": "Services rendered",
  "amount": "80000.00",
  "currency": "NGN",
  "route": "bank_transfer",
  "type": "fiat",
  "status": "created",
  "fee": "2.50",
  "inputCurrency": "EUR",
  "inputAmount": "52.50",
  "fxRate": "1600.00",
  "beneficiary": {
    "id": "456e7890-e89b-12d3-a456-426614174000",
    "name": "Adaeze Obi",
    "type": "individual",
    "email": "adaeze.obi@example.com",
    "country": "NG",
    "accounts": [{
      "id": "123e4567-e89b-12d3-a456-426614174001",
      "type": "bank_account",
      "currency": "NGN",
      "status": "active",
      "data": {
        "bankCode": "044",
        "crAccount": "1234567890"
      },
      "createdAt": "2026-01-15T10:25:00Z",
      "updatedAt": "2026-01-15T10:25:00Z"
    }],
    "status": "active",
    "createdAt": "2026-01-15T10:25:00Z",
    "updatedAt": "2026-01-15T10:25:00Z"
  },
  "createdAt": "2026-01-15T10:30:00Z",
  "updatedAt": "2026-01-15T10:30:00Z"
}

The FX fields show what was actually debited: inputAmount is the total charged in inputCurrency (including the fee), and fxRate is the rate applied to convert to the destination currency.

Error Handling

Common errors when creating payouts:

try {
  const response = await fetch('https://api.sandbox.zuba.com/v1/payouts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    },
    body: JSON.stringify(payoutData)
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message);
  }

  const payout = await response.json();
} catch (error) {
  console.error('Payout failed:', error.message);
  // Handle specific errors:
  // - Insufficient balance (code INSUFFICIENT_BALANCE): add funds, then resend with the same clientRef
  // - Invalid beneficiary
  // - Invalid bank code (must be a recognised CBN/NIP code)
  // - Invalid account number (crAccount must be exactly 10 digits)
  // - Currency not supported
}

Next Steps

Learn about batch payouts for processing multiple payouts efficiently
Set up webhook notifications to receive real-time payout updates
Explore error handling for robust production implementations

Complete Example

Here’s a complete example combining all steps:

async function sendFirstPayout() {
  const baseURL = 'https://api.sandbox.zuba.com/v1';
  const headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  };

  try {
    // 1. Create beneficiary
    const beneficiary = await fetch(`${baseURL}/beneficiaries`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        name: "Adaeze Obi",
        email: "adaeze.obi@example.com",
        country: "NG",
        address: "12 Marina Road",
        city: "Lagos",
        postcode: "101233",
        accounts: [{
          type: "bank_account",
          currency: "NGN",
          data: {
            bankCode: "044",
            crAccount: "1234567890"
          }
        }]
      })
    }).then(r => r.json());

    console.log('Beneficiary created:', beneficiary.id);

    // 2. Create payout using beneficiary ID (recommended)
    const payout = await fetch(`${baseURL}/payouts`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        clientRef: "PAYOUT-0001",
        amount: "80000.00",
        inputCurrency: "EUR",
        currency: "NGN",
        route: "bank_transfer",
        beneficiary: {
          id: beneficiary.id // Reference the beneficiary by ID
        },
        reference: "Welcome payment",
        description: "Welcome payment"
      })
    }).then(r => r.json());

    console.log('Payout created:', payout.id);
    return payout;

  } catch (error) {
    console.error('Error:', error);
    throw error;
  }
}

Get Started

Core Concepts

Guides

Your First Payout

Prerequisites

Step 1: Create a Beneficiary

Step 2: Create Your First Payout

Step 3: Monitor Payout Status

Step 4: Handle the Response

Error Handling

Next Steps

Complete Example

​Prerequisites

​Step 1: Create a Beneficiary

​Step 2: Create Your First Payout

​Step 3: Monitor Payout Status

​Step 4: Handle the Response

​Error Handling

​Next Steps

​Complete Example

Prerequisites

Step 1: Create a Beneficiary

Step 2: Create Your First Payout

Step 3: Monitor Payout Status

Step 4: Handle the Response

Error Handling

Next Steps

Complete Example