Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.zuba.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Setup your environment

Learn how to update your docs locally and deploy them to the public.

​
Prerequisites

Before you begin, ensure you have:
  • A Zuba account with API access
  • Your API credentials (API key and secret)
  • Basic knowledge of REST APIs

​
Get your API credentials

  1. Log in to your Zuba Test Dashboard
  2. Navigate to API Settings
  3. Click Generate API Credentials
  4. Save your Client ID, Client Secret, and Token URL 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:
LimitRequestsWindow
Burst10per second
Sustained100per minute
Hourly1,000per hour
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, you need to create a beneficiary with their banking details: 
curl -X POST "https://api-test.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": "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"
      }
    }]
  }'

​
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-test.zuba.com/ledger/balances" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
If your account has zero balance, payouts will fail. Contact your account manager or use the dashboard to fund your account before proceeding.

​
Send your first payout

Now you can send a payout to your beneficiary. RECOMMENDED: Reference the beneficiary by ID (from the previous step). Note that amount is passed as a string to avoid floating-point precision issues. 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): 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-test.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"
  }'

​
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-test.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"
  }'

​
Track payout status

You can check the status of your payout: 
curl -X GET "https://api-test.zuba.com/v1/payouts/YOUR_PAYOUT_ID" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​
Next Steps

Authentication

Learn about secure authentication methods

Webhooks

Set up real-time payment notifications

Batch Payouts

Process multiple payments efficiently

API Reference

Explore the complete API documentation