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.

​
Introduction

The Zuba Payment Platform API is organized around REST principles. Our API has predictable resource-oriented URLs requests and responses are JSON-encoded, and uses standard HTTP response codes, authentication, and verbs.

​
Base URL

Production: 
https://api.zuba.com
Test: 
https://api-test.zuba.com

​
Authentication

The Zuba API uses OAuth 2.0 Client Credentials flow for authentication. You can generate your credentials in the Zuba Dashboard (test) or Production Dashboard. See our Authentication Guide for detailed instructions on obtaining access tokens. Include your access token in the Authorization header: 
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...

​
Request Format

All POST requests should include the Content-Type header: 
Content-Type: application/json

​
Response Format

All responses are returned in JSON format:

​
Example Success Response

{
    "userId": "user123",
    "clientId": "d7c75cf2-322f-4d27-b5fc-3418d1917309",
    "balances": [
        {
            "currency": "EUR",
            "balance": 87.57104914,
            "pendingIn": 0,
            "pendingOut": 0,
            "totalBalance": 87.57104914,
            "isActive": true,
            "lastTransactionAt": "2026-01-12T12:50:48.792Z"
        }
    ],
    "totalValueEur": 87.57104914,
    "primaryCurrency": "EUR",
    "calculatedAt": "2026-01-15T12:11:24.559Z"
}

​
Error Response

{
    "statusCode": 400,
    "message": "Validation failed",
    "error": "BAD_REQUEST",
    "timestamp": "2026-01-15T12:12:24.062Z",
    "path": "/v1/beneficiaries",
    "details": [
        {
            "field": "accounts.0.data",
            "message": "bankCode '123123333' is not a recognized Nigerian bank code",
            "value": {
                "crAccount": "1234567890",
                "bankCode": "123123333"
            }
        }
    ]
}

​
HTTP Status Codes

The Zuba API uses conventional HTTP response codes:
CodeDescription
200Success - Request completed successfully
201Created - Resource created successfully
400Bad Request - Invalid request parameters
401Unauthorized - Invalid or missing access token
403Forbidden - Insufficient permissions
404Not Found - Resource not found
422Unprocessable Entity - Validation errors
500Internal Server Error - Something went wrong

​
Pagination

List endpoints support cursor-based pagination:

​
Request Parameters

  • cursor - Pagination cursor (timestamp)
  • limit - Number of items per page (max 100, default 20)

​
Example Response Format

{
  "payouts": [
    // Array of items
  ],
  "nextCursor": "2024-01-15T10:30:00Z",
  "hasMore": true
}

​
Idempotency

The clientRef is the idempotency attribute - clients are expected to provide a unique reference for each payout request, allowing safe retries without creating duplicates. Using the same idempotency key will return the an error and a HTTP 400 status. 
{
  "message": "Payout with this client reference already exists",
  "error": "Bad Request",
  "statusCode": 400
}

​
Webhooks

The Zuba API can send webhook notifications for events: 
{
  "event": "payout.completed",
  "data": {
    "id": "pay_1234567890",
    "status": "COMPLETED"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}
Learn more in our Webhooks Guide.

​
API Versioning

The current API version is v1. Version is specified in the URL path: 
POST https://api.zuba.com/v1/payouts

​
Testing

Use test environment credentials for development:
  • Test Dashboard: https://dash-test.zuba.com
  • Test Base URL: https://api-test.zuba.com
  • Test Token URL: https://zuba-test.us.auth0.com/oauth/token
Test mode provides:
  • Simulated payment processing
  • No real money movement
  • Access to test data and scenarios
  • Webhook testing capabilities

​
Support

Need help with integration? Contact our team:
  • Email: hello@zuba.com
  • Documentation: Browse the complete API reference below

​
Next Steps

Quickstart Guide

Send your first payout in minutes

Payouts API

Send money globally to beneficiaries

Ledger System

Double-entry accounting and transaction tracking

Webhooks

Receive real-time event notifications