> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dubu Pay REST API overview and conventions

> The Dubu Pay REST API reference: base URL, authentication methods, response envelopes, pagination, rate limits, and sandbox vs production.

The Dubu Pay REST API gives your business programmatic access to payments, trading, and merchant management. Every resource lives under a single base URL, uses JSON for all request and response bodies, and follows consistent conventions across all endpoints so you can integrate once and expect predictable behaviour everywhere.

## Base URL

All API requests go to:

```
https://api.dubupay.com/api/v1
```

Every path in this documentation is relative to that base URL — for example, `POST /auth/login` means `POST https://api.dubupay.com/api/v1/auth/login`.

## Request format

Send all request bodies as JSON and include the `Content-Type` header:

```
Content-Type: application/json
```

Query parameters (for filtering, pagination, etc.) are plain URL parameters and do not require a special content-type header.

## Authentication

Protected endpoints require you to identify yourself on every request. Dubu Pay supports two methods — use whichever fits your integration.

**Bearer token (JWT)**

Include the access token you received from `POST /auth/login` or `POST /auth/refresh` in the `Authorization` header:

```
Authorization: Bearer <access_token>
```

Access tokens expire after 15 minutes. Use `POST /auth/refresh` to rotate them without requiring the user to log in again.

**API key**

For server-to-server integrations, pass your API key in the `X-Api-Key` header:

```
X-Api-Key: dubu_sk_live_<32chars>
```

API keys are scoped to your merchant account and do not expire unless you revoke them. Live keys follow the `dubu_sk_live_` prefix; test keys use `dubu_sk_test_`.

If you have configured an IP whitelist for your merchant account, requests from non-whitelisted addresses are rejected with `403 IP_NOT_WHITELISTED` regardless of which auth method you use.

## Response envelope

Every response body is a JSON object with a `success` field that tells you immediately whether the call succeeded.

**Success**

```json theme={null}
{
  "success": true,
  "data": { ... }
}
```

**Error**

```json theme={null}
{
  "success": false,
  "message": "Human-readable summary of what went wrong",
  "errors": [
    { "field": "email", "message": "Invalid email address" }
  ]
}
```

The `errors` array is present on validation errors (HTTP 400) and contains one object per invalid field. For non-validation errors the array may be omitted or empty.

## Pagination

List endpoints accept two query parameters:

| Parameter | Type    | Default | Description                              |
| --------- | ------- | ------- | ---------------------------------------- |
| `page`    | integer | `1`     | The page number to retrieve (1-indexed). |
| `limit`   | integer | `20`    | Number of records per page.              |

Paginated responses include a `meta` object inside `data`:

```json theme={null}
{
  "success": true,
  "data": {
    "items": [ ... ],
    "meta": {
      "total": 142,
      "page": 1,
      "limit": 20,
      "total_pages": 8
    }
  }
}
```

## Rate limiting

The API enforces a limit of **100 requests per minute** per merchant. Authentication endpoints (`/auth/register`, `/auth/login`, `/auth/verify-email`, `/auth/resend-otp`, `/auth/forgot-password`, `/auth/reset-password`) use a stricter limit to protect against brute-force attacks.

When you exceed the limit the API returns `429 Too Many Requests`. The response includes a `Retry-After` header indicating how many seconds to wait before retrying.

## Environments

| Environment    | Base URL                                     | Description                                                                |
| -------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
| **Sandbox**    | `https://api.dubupay.com/api/v1` (test keys) | Use `dubu_sk_test_` API keys. Payments are simulated; no real money moves. |
| **Production** | `https://api.dubupay.com/api/v1` (live keys) | Use `dubu_sk_live_` API keys. Real transactions.                           |

The base URL is the same for both environments — your API key prefix (`test` vs `live`) determines which environment you operate in.

## Versioning

The current API version is `v1`. The version is part of the URL path. When breaking changes are introduced, a new version will be published and the old version will continue to work with a deprecation notice.