API Reference

Introduction

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

Base URL

Production:

https://api.zuba.com

Sandbox:

https://api.sandbox.zuba.com

Authentication

The Zuba API uses the OAuth 2.0 Client Credentials flow for authentication. You can generate your credentials in the Zuba Dashboard (Sandbox) 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

The example below is the response body of GET /v1/ledger/balances. 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.57",
    "primaryCurrency": "EUR",
    "calculatedAt": "2026-01-15T12:11:24.559Z"
}

Error Response

Most errors use a JSON envelope with statusCode, message, and error fields. Validation errors also carry a details array identifying the offending fields:

{
    "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"
            }
        }
    ]
}

Some errors, including Idempotency-Key errors and all unexpected 500s, are returned as RFC 9457 problem details instead, with Content-Type: application/problem+json and a different body shape:

{
    "type": "https://errors.zuba.com/invalid-request/idempotency-key-reused",
    "title": "The Idempotency-Key was reused with different parameters",
    "status": 422,
    "detail": "The Idempotency-Key was reused with different parameters",
    "code": "IDEMPOTENCY_KEY_REUSED",
    "category": "INVALID_REQUEST",
    "request_id": "0f6a2f3e-9d0b-4c66-8b7a-2f4f4bfa61a2",
    "retryable": false,
    "instance": "/v1/payouts"
}

Check the response Content-Type header and handle both shapes: a parser keyed exclusively on message and statusCode will break on application/problem+json responses. On problem responses, branch on type or code, and use retryable to decide whether a retry can succeed.

HTTP Status Codes

The Zuba API uses conventional HTTP response codes:

Code	Description
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request parameters or validation errors
`401`	Unauthorized - Invalid or missing access token
`403`	Forbidden - Insufficient permissions, or the requested capability is not enabled for your account. Contact support to enable additional payment methods or currencies.
`404`	Not Found - Resource not found
`409`	Conflict - A request with the same `Idempotency-Key` is still in flight; retry the identical request
`422`	Unprocessable Entity - The request was understood but declined (e.g. invalid recipient details, `Idempotency-Key` reused with a different body)
`429`	Too Many Requests - Rate limit exceeded; retry with backoff
`500`	Internal Server Error - Something went wrong

Rate Limits

Requests are rate limited across three windows:

Window	Limit
1 second	10 requests
1 minute	100 requests
1 hour	1,000 requests

Exceeding any window returns HTTP 429 Too Many Requests. Back off and retry with exponentially increasing delays.

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

Two mechanisms prevent duplicate payouts:

clientRef deduplication

Every payout must carry a unique clientRef. A request that reuses an existing clientRef is rejected with HTTP 400, so a resubmission can never create a duplicate payout.

Idempotency-Key header

POST /v1/payouts also accepts an optional Idempotency-Key header, a client-generated key scoped to your workspace:

Same key, same body: the original response is replayed; no second payout is created.
Same key, different body: rejected with HTTP 422 (IDEMPOTENCY_KEY_REUSED).
Repeat while the first request is still in flight: HTTP 409 (retryable); retry the identical request to receive the stored response.
Keys expire 24 hours after the original request completes; a repeat after expiry is treated as a new request.

Webhooks

The Zuba API sends webhook notifications for events such as payout status changes. Every delivery is a JSON POST with this envelope:

{
  "id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "type": "payout.paid",
  "createdAt": "2026-03-23T14:30:00.000Z",
  "test": false,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "clientRef": "your-reference-123",
    "amount": "1000.00000000",
    "currency": "USD",
    "status": "paid",
    "completedAt": "2026-03-23T14:29:58.000Z"
  }
}

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 Sandbox credentials for development:

Sandbox Dashboard: https://sandbox.zuba.com
Sandbox Base URL: https://api.sandbox.zuba.com
Sandbox Token URL: https://zuba-test.us.auth0.com/oauth/token

The Sandbox 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

Send money globally to beneficiaries

Ledger System

Double-entry accounting and transaction tracking

Webhooks

Receive real-time event notifications

​Introduction

​Base URL

​Authentication

​Request Format

​Response Format

​Example Success Response

​Error Response

​HTTP Status Codes

​Rate Limits

​Pagination

​Request Parameters

​Example Response Format

​Idempotency

​clientRef deduplication

​Idempotency-Key header

​Webhooks

​API Versioning

​Testing

​Support

​Next Steps

Quickstart Guide

Payouts

Ledger System

Webhooks

Introduction

Base URL

Authentication

Request Format

Response Format

Example Success Response

Error Response

HTTP Status Codes

Rate Limits

Pagination

Request Parameters

Example Response Format

Idempotency

clientRef deduplication

Idempotency-Key header

Webhooks

API Versioning

Testing

Support

Next Steps