> ## 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.

# API Reference

> Complete API reference for the Zuba Payment Platform

## 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](https://sandbox.zuba.com) (test) or [Production Dashboard](https://dash.zuba.com).

See our [Authentication Guide](/authentication) for detailed instructions on obtaining access tokens.

Include your access token in the `Authorization` header:

```http theme={"dark"}
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6...
```

## Request Format

All POST requests should include the `Content-Type` header:

```http theme={"dark"}
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:

```json theme={"dark"}
{
    "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

```json theme={"dark"}
{
    "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:

| Code  | Description                                                                                                                                                                                                                              |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | Success - Request completed successfully                                                                                                                                                                                                 |
| `201` | Created - Resource created successfully                                                                                                                                                                                                  |
| `400` | Bad Request - Invalid request parameters                                                                                                                                                                                                 |
| `401` | Unauthorized - Invalid or missing access token                                                                                                                                                                                           |
| `403` | Forbidden - 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. |
| `404` | Not Found - Resource not found                                                                                                                                                                                                           |
| `422` | Unprocessable Entity - Validation errors                                                                                                                                                                                                 |
| `500` | Internal 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

```json theme={"dark"}
{
  "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.

```json theme={"dark"}
{
  "message": "Payout with this client reference already exists",
  "error": "Bad Request",
  "statusCode": 400
}
```

## Webhooks

The Zuba API can send webhook notifications for events:

```json theme={"dark"}
{
  "event": "payout.completed",
  "data": {
    "id": "pay_1234567890",
    "status": "COMPLETED"
  },
  "createdAt": "2024-01-15T10:30:00Z"
}
```

Learn more in our [Webhooks Guide](/guides/webhooks).

## 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
```

<Note>
  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.
</Note>

## 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](mailto:support@zuba.com)
* **Documentation**: Browse the complete API reference below

## Next Steps

<CardGroup cols={2}>
  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Send your first payout in minutes
  </Card>

  <Card title="Payouts API" icon="money-bill-transfer" href="/concepts/payouts">
    Send money globally to beneficiaries
  </Card>

  <Card title="Ledger System" icon="book-open" href="/concepts/ledger">
    Double-entry accounting and transaction tracking
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receive real-time event notifications
  </Card>
</CardGroup>