# API Documentation — version 1

Copyright © 2026 Victor Idonor. All rights reserved.

Base path: `/api/v1`. All requests and responses are JSON; send `Accept: application/json`.

## Conventions

- **Authentication**: `Authorization: Bearer <token>`. Tokens expire 30 days after issue.
- **Success**: `{ "data": { ... } }`, or `{ "message": "..." }` for actions with nothing to return.
- **Validation failure**: `422` with `{ "message": "...", "errors": { "field": ["..."] } }`.
- **Not authenticated**: `401`. **Not allowed**: `403`. **Rate limited**: `429`.
- Every response carries `X-Request-Id`; quote it when reporting a problem.
- Internal numeric IDs are never returned. Users are identified by `reference`.

## User object

| Field | Type | Notes |
| --- | --- | --- |
| `reference` | string | Public identifier, e.g. `USR_01J...` |
| `first_name`, `last_name` | string | |
| `email` | string | |
| `phone` | string | E.164, e.g. `+2348031234567` |
| `email_verified` | boolean | |
| `kyc_tier` | integer | `0` until identity is verified |
| `has_transaction_pin` | boolean | |
| `two_factor_enabled` | boolean | |
| `created_at` | string | ISO 8601 |

## POST /auth/register

Creates a customer account and returns a token. A verification email is sent.

| Field | Required | Rules |
| --- | --- | --- |
| `first_name`, `last_name` | yes | up to 60 characters |
| `email` | yes | unique |
| `phone` | yes | Nigerian mobile number in any common format; unique |
| `password`, `password_confirmation` | yes | at least 10 characters with upper case, lower case and a number |
| `device_name` | yes | label for the token, e.g. `Pixel 9` |

`201`:

```json
{
  "data": {
    "token": "1|...",
    "token_type": "Bearer",
    "expires_at": "2026-12-18T01:00:00+00:00",
    "user": { "reference": "USR_...", "email": "ada@example.com" }
  }
}
```

Limit: 10 requests a minute.

## POST /auth/login

| Field | Required | Notes |
| --- | --- | --- |
| `email`, `password` | yes | |
| `device_name` | yes | |
| `code` | when two-factor is on | six-digit authenticator code |

- `200`: same body as registration.
- `422` with `"two_factor_required": true` when the account has two-factor and no `code` was sent.
- `422` with an `email` error for wrong credentials, a suspended account, or too many attempts (five failures lock the email and IP pair for 15 minutes).
- `403` for administrator accounts, which sign in on the web only.

Limit: 20 requests a minute.

## GET /auth/me

Authenticated. Returns `{ "data": <user object> }`.

## POST /auth/logout

Authenticated. Revokes the token used for the request. Returns `{ "message": "Signed out." }`.

## Money object

Every amount is an object, never a bare number:

```json
{ "minor": 1150000, "currency": "NGN", "formatted": "₦11,500.00" }
```

`minor` is whole kobo. Do arithmetic on `minor`; show `formatted`.

## GET /wallet

Authenticated. The caller's own wallet; it is opened on first request.

```json
{
  "data": {
    "reference": "WAL_...",
    "currency": "NGN",
    "status": "active",
    "balance":   { "minor": 1400000, "currency": "NGN", "formatted": "₦14,000.00" },
    "held":      { "minor": 250000,  "currency": "NGN", "formatted": "₦2,500.00" },
    "available": { "minor": 1150000, "currency": "NGN", "formatted": "₦11,500.00" }
  }
}
```

`status` is `active` or `frozen`. Spend against `available`, not `balance`.

## GET /wallet/transactions

Authenticated. The caller's statement, newest first.

| Query | Notes |
| --- | --- |
| `direction` | `credit` (money in) or `debit` (money out) |
| `per_page` | 1 to 50, default 15 |
| `page` | page number |

Each item: `reference`, `type`, `description`, `direction`, `amount`, `balance_after`, `posted_at`. Standard `links` and `meta` pagination objects accompany `data`.

## Idempotency

Endpoints that move money (from Milestone 5) require an `Idempotency-Key` header: 8 to 100 letters, digits, dashes, underscores, colons or dots, unique per attempt at one action.

- Same key, same payload: the first response is returned again with `Idempotent-Replayed: true`. Nothing runs twice.
- Same key, different payload: `422`.
- Same key while the first request is still running: `409`.
- Missing or malformed key: `400`.

Generate the key once when the user confirms an action and reuse it for every retry of that action.
