Quickstart

Set up your environment

Get your API credentials, fund your Sandbox account, and send your first payout, all in a few minutes.

Prerequisites

Before you begin, ensure you have:

A Zuba account with API access
Your API credentials (Client ID and Client Secret)
Basic knowledge of REST APIs

Get your API credentials

Log in to your Zuba Sandbox Dashboard
Navigate to API Settings
Click Generate API Key or Create API Credentials
Save your Client ID, Client Secret, Token URL, and Audience securely

See the Authentication Guide for detailed instructions on obtaining access tokens.

Never expose your Client Secret in client-side code or public repositories. Always keep it secure on your server.

Rate Limits

The API enforces rate limits to ensure fair usage and platform stability:

Limit	Requests	Window
Sustained	100	per minute

Limits are per client IP address, and some endpoints carry their own. If you exceed these limits, you’ll receive a 429 Too Many Requests response. Implement exponential backoff in your integration to handle rate limiting gracefully.

Create your first beneficiary

Before sending payouts, create a beneficiary with their banking details. This example creates a Nigerian beneficiary with an NGN bank account; the payout in the next step delivers to it over the local bank_transfer rail:

curl -X POST "https://api.sandbox.zuba.com/v1/beneficiaries" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john.doe@example.com",
    "country": "NG",
    "address": "12 Marina Road",
    "city": "Lagos",
    "accounts": [{
      "type": "bank_account",
      "currency": "NGN",
      "data": {
        "bankCode": "044",
        "crAccount": "1234567890"
      }
    }]
  }'

const beneficiary = await fetch('https://api.sandbox.zuba.com/v1/beneficiaries', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Doe',
    email: 'john.doe@example.com',
    country: 'NG',
    address: '12 Marina Road',
    city: 'Lagos',
    accounts: [{
      type: 'bank_account',
      currency: 'NGN',
      data: {
        bankCode: '044',
        crAccount: '1234567890'
      }
    }]
  })
});

const beneficiaryData = await beneficiary.json();
console.log(beneficiaryData);

import requests

beneficiary = requests.post(
    'https://api.sandbox.zuba.com/v1/beneficiaries',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'name': 'John Doe',
        'email': 'john.doe@example.com',
        'country': 'NG',
        'address': '12 Marina Road',
        'city': 'Lagos',
        'accounts': [{
            'type': 'bank_account',
            'currency': 'NGN',
            'data': {
                'bankCode': '044',
                'crAccount': '1234567890'
            }
        }]
    }
)

beneficiary_data = beneficiary.json()
print(beneficiary_data)

import java.net.http.*;
import java.net.URI;
import com.google.gson.Gson;
import com.google.gson.JsonObject;
import com.google.gson.JsonArray;

HttpClient client = HttpClient.newHttpClient();

JsonObject accountData = new JsonObject();
accountData.addProperty("bankCode", "044");
accountData.addProperty("crAccount", "1234567890");

JsonObject account = new JsonObject();
account.addProperty("type", "bank_account");
account.addProperty("currency", "NGN");
account.add("data", accountData);

JsonArray accounts = new JsonArray();
accounts.add(account);

JsonObject requestBody = new JsonObject();
requestBody.addProperty("name", "John Doe");
requestBody.addProperty("email", "john.doe@example.com");
requestBody.addProperty("country", "NG");
requestBody.addProperty("address", "12 Marina Road");
requestBody.addProperty("city", "Lagos");
requestBody.add("accounts", accounts);

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.zuba.com/v1/beneficiaries"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(new Gson().toJson(requestBody)))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

JsonObject beneficiaryData = new Gson().fromJson(response.body(), JsonObject.class);
System.out.println(beneficiaryData);

bankCode accepts either the 3-digit CBN short code (e.g. 044) or the 6-digit NIP long code; crAccount is the 10-digit account number. The payout currency must match the currency of one of the beneficiary’s accounts. For other destination currencies and account shapes (IBAN, US bank accounts, crypto wallets, mobile money), see Payouts.

Check your account balance

Before sending payouts, ensure your account has sufficient funds. You can check your balance across all currencies:

curl -X GET "https://api.sandbox.zuba.com/v1/ledger/balances" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

const balances = await fetch('https://api.sandbox.zuba.com/v1/ledger/balances', {
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  }
});

const balanceData = await balances.json();
console.log(balanceData);

import requests

balances = requests.get(
    'https://api.sandbox.zuba.com/v1/ledger/balances',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
)

balance_data = balances.json()
print(balance_data)

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.zuba.com/v1/ledger/balances"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .GET()
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

JsonObject balanceData = new Gson().fromJson(response.body(), JsonObject.class);
System.out.println(balanceData);

Payouts fail if your balance is zero. In the Sandbox you can fund your workspace yourself; see Sandbox testing. In production, fund your account via the dashboard or contact your account manager.

Send your first payout

Now send a payout to your beneficiary, referencing them by ID from the previous step (recommended). amount is passed as a decimal string to avoid floating-point precision issues. Currency fields: inputCurrency is the balance you pay from, while currency is what the beneficiary receives (converted automatically if different). Sender types: senderInfo.type is 'individual' (default when omitted) for natural-person senders, or 'business' for legal entities. The examples below use an individual sender; for a business sender, see Business sender example.

curl -X POST "https://api.sandbox.zuba.com/v1/payouts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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": "BENEFICIARY_ID_FROM_PREVIOUS_STEP"
    },
    "reference": "Invoice #INV-001",
    "description": "Payment for marketing services"
  }'

const payout = await fetch('https://api.sandbox.zuba.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    '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: beneficiaryData.id
    },
    reference: 'Invoice #INV-001',
    description: 'Payment for marketing services'
  })
});

const payoutData = await payout.json();
console.log(payoutData);

import requests

payout = requests.post(
    'https://api.sandbox.zuba.com/v1/payouts',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        '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': beneficiary_data['id']
        },
        'reference': 'Invoice #INV-001',
        'description': 'Payment for marketing services'
    }
)

payout_data = payout.json()
print(payout_data)

JsonObject beneficiaryRef = new JsonObject();
beneficiaryRef.addProperty("id", beneficiaryData.get("id").getAsString());

JsonObject senderInfo = new JsonObject();
senderInfo.addProperty("firstName", "Jack");
senderInfo.addProperty("lastName", "Jones");
senderInfo.addProperty("address", "456 London Road");
senderInfo.addProperty("city", "London");
senderInfo.addProperty("postalCode", "SW1A 1AA");
senderInfo.addProperty("country", "GB");
senderInfo.addProperty("dateOfBirth", "1985-06-15");

JsonObject payoutRequest = new JsonObject();
payoutRequest.addProperty("clientRef", "PAYOUT-INV-001");
payoutRequest.addProperty("amount", "1000.00");
payoutRequest.addProperty("inputCurrency", "EUR");
payoutRequest.addProperty("currency", "NGN");
payoutRequest.addProperty("route", "bank_transfer");
payoutRequest.add("senderInfo", senderInfo);
payoutRequest.add("beneficiary", beneficiaryRef);
payoutRequest.addProperty("reference", "Invoice #INV-001");
payoutRequest.addProperty("description", "Payment for marketing services");

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.zuba.com/v1/payouts"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(new Gson().toJson(payoutRequest)))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

JsonObject payoutData = new Gson().fromJson(response.body(), JsonObject.class);
System.out.println(payoutData);

clientRef is your idempotency reference: it must be unique per workspace, and you can look a payout up by it later. For safe retries, you can also send an optional Idempotency-Key header on POST /v1/payouts: a repeat with the same key and body replays the original response instead of creating a duplicate payout.

Business sender example

When the sender is a legal entity rather than a natural person, set senderInfo.type to 'business' and provide companyName, registrationNumber, and country. The registrationNumber is the company’s official registration identifier and is used as the AML pivot for sanctions and UBO screening. Business senders do not carry firstName, lastName, or dateOfBirth.

curl -X POST "https://api.sandbox.zuba.com/v1/payouts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "clientRef": "PAYOUT-INV-002",
    "amount": "1000.00",
    "inputCurrency": "EUR",
    "currency": "NGN",
    "route": "bank_transfer",
    "senderInfo": {
      "type": "business",
      "companyName": "Acme Trading Ltd",
      "registrationNumber": "12345678",
      "address": "1 Finsbury Square",
      "city": "London",
      "postalCode": "EC2A 1AE",
      "country": "GB"
    },
    "beneficiary": {
      "id": "BENEFICIARY_ID_FROM_PREVIOUS_STEP"
    },
    "reference": "Invoice #INV-002",
    "description": "Payment for marketing services"
  }'

const payout = await fetch('https://api.sandbox.zuba.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientRef: 'PAYOUT-INV-002',
    amount: '1000.00',
    inputCurrency: 'EUR',
    currency: 'NGN',
    route: 'bank_transfer',
    senderInfo: {
      type: 'business',
      companyName: 'Acme Trading Ltd',
      registrationNumber: '12345678',
      address: '1 Finsbury Square',
      city: 'London',
      postalCode: 'EC2A 1AE',
      country: 'GB'
    },
    beneficiary: {
      id: beneficiaryData.id
    },
    reference: 'Invoice #INV-002',
    description: 'Payment for marketing services'
  })
});

const payoutData = await payout.json();
console.log(payoutData);

import requests

payout = requests.post(
    'https://api.sandbox.zuba.com/v1/payouts',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'clientRef': 'PAYOUT-INV-002',
        'amount': '1000.00',
        'inputCurrency': 'EUR',
        'currency': 'NGN',
        'route': 'bank_transfer',
        'senderInfo': {
            'type': 'business',
            'companyName': 'Acme Trading Ltd',
            'registrationNumber': '12345678',
            'address': '1 Finsbury Square',
            'city': 'London',
            'postalCode': 'EC2A 1AE',
            'country': 'GB'
        },
        'beneficiary': {
            'id': beneficiary_data['id']
        },
        'reference': 'Invoice #INV-002',
        'description': 'Payment for marketing services'
    }
)

payout_data = payout.json()
print(payout_data)

JsonObject businessSenderInfo = new JsonObject();
businessSenderInfo.addProperty("type", "business");
businessSenderInfo.addProperty("companyName", "Acme Trading Ltd");
businessSenderInfo.addProperty("registrationNumber", "12345678");
businessSenderInfo.addProperty("address", "1 Finsbury Square");
businessSenderInfo.addProperty("city", "London");
businessSenderInfo.addProperty("postalCode", "EC2A 1AE");
businessSenderInfo.addProperty("country", "GB");

JsonObject businessPayoutRequest = new JsonObject();
businessPayoutRequest.addProperty("clientRef", "PAYOUT-INV-002");
businessPayoutRequest.addProperty("amount", "1000.00");
businessPayoutRequest.addProperty("inputCurrency", "EUR");
businessPayoutRequest.addProperty("currency", "NGN");
businessPayoutRequest.addProperty("route", "bank_transfer");
businessPayoutRequest.add("senderInfo", businessSenderInfo);
businessPayoutRequest.add("beneficiary", beneficiaryRef);
businessPayoutRequest.addProperty("reference", "Invoice #INV-002");
businessPayoutRequest.addProperty("description", "Payment for marketing services");

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.zuba.com/v1/payouts"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(new Gson().toJson(businessPayoutRequest)))
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

JsonObject payoutData = new Gson().fromJson(response.body(), JsonObject.class);
System.out.println(payoutData);

Track payout status

Check the status of your payout at any time:

curl -X GET "https://api.sandbox.zuba.com/v1/payouts/YOUR_PAYOUT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

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

const statusData = await status.json();
console.log('Payout status:', statusData.status);

import requests

status = requests.get(
    f'https://api.sandbox.zuba.com/v1/payouts/{payout_data["id"]}',
    headers={
        'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    }
)

status_data = status.json()
print(f'Payout status: {status_data["status"]}')

String payoutId = payoutData.get("id").getAsString();

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.sandbox.zuba.com/v1/payouts/" + payoutId))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .GET()
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());

JsonObject statusData = new Gson().fromJson(response.body(), JsonObject.class);
System.out.println("Payout status: " + statusData.get("status").getAsString());

status is one of created, queued, processing, paid, failed, or cancelled; see Payout statuses for what each means. For push notifications instead of polling, set up webhooks.

Next Steps

Authentication

Learn about secure authentication methods

Webhooks

Set up real-time payout notifications

Batch Payouts

Process multiple payouts efficiently

API Reference

Explore the complete API documentation

Get Started

Core Concepts

Guides

Set up your environment

Prerequisites

Get your API credentials

Rate Limits

Create your first beneficiary

Check your account balance

Send your first payout

Business sender example

Track payout status

Next Steps

Authentication

Webhooks

Batch Payouts

API Reference

​Set up your environment

​Prerequisites

​Get your API credentials

​Rate Limits

​Create your first beneficiary

​Check your account balance

​Send your first payout

​Business sender example

​Track payout status

​Next Steps

Authentication

Webhooks

Batch Payouts

API Reference

Set up your environment

Prerequisites

Get your API credentials

Rate Limits

Create your first beneficiary

Check your account balance

Send your first payout

Business sender example

Track payout status

Next Steps