Skip to main content

​
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.sandbox.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

Monetary values are always decimal strings, never JSON numbers: 
{
    "userId": "user123",
    "clientId": "d7c75cf2-322f-4d27-b5fc-3418d1917309",
    "balances": [
        {
            "currency": "EUR",
            "balance": "87.57104914",
            "pendingIn": "0.00",
            "pendingOut": "0.00",
            "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, or the requested capability is not enabled for your account (METHOD_NOT_ENTITLED / CAPABILITY_DISABLED). Check GET /v1/capabilities for the payment methods and currencies available to you.
404Not Found - Resource not found
422Unprocessable Entity - Validation errors
500Internal Server Error - Something went wrong

​
Pagination

List endpoints use cursor pagination. Results are ordered newest first. Pass the nextCursor returned by the previous page as cursor to fetch the next page.

​
Request Parameters

  • cursor - Opaque cursor returned by the previous page
  • limit - Number of items per page (minimum 1, maximum 100, default 20)

​
Example Response Format

{
  "object": "payout.list",
  "data": [
    // Array of items
  ],
  "hasMore": true,
  "nextCursor": "eyJ2IjoxLCJjcmVhdGVkQXQiOiIyMDI2LTAxLTAxVDAwOjAwOjAwLjAwMFoiLCJpZCI6IjEyM2U0NTY3LWU4OWItNDJkMy1hNDU2LTQyNjYxNDE3NDAwMCJ9"
}
When hasMore is true, pass nextCursor as cursor on the next request. When hasMore is false, nextCursor is null.

​
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 API version is specified in the URL path. All endpoints are served under /v1: 
POST https://api.zuba.com/v1/payouts
GET https://api.zuba.com/v1/payouts
FX and ledger endpoints were historically served at unversioned paths (/fx/..., /ledger/...). Those legacy URLs continue to work as aliases of the canonical /v1/fx/... and /v1/ledger/... paths, but are deprecated — use the /v1 form in new integrations.

​
Testing

Use test environment credentials for development:
  • Test Dashboard: https://sandbox.zuba.com
  • Test Base URL: https://api.sandbox.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: support@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