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

# API Reference Overview

> FYATU CaaS API v3.20 — base URL, request format, authentication, response envelope, pagination, rate limits, and all 21 endpoints.

# API Reference — v3.20

## Base URL

All v3.20 requests go to:

```
https://api.fyatu.com/api/v3.20
```

## Request Format

* **Body**: JSON — set `Content-Type: application/json` on all write requests.
* **Timestamps**: ISO 8601 (`2026-05-22T10:00:00Z`) or `YYYY-MM-DD` where noted.
* **Amounts in requests**: Full currency units (e.g. `50.00` = \$50.00).
* **Amounts in responses**: Always in **cents** as `int64` (e.g. `amountCents: 5000` = \$50.00).

## Authentication

All endpoints require an API key passed as a Bearer token:

```bash theme={null}
Authorization: Bearer fyatu_live_abc123def456...
```

Keys are environment-scoped (`LIVE` or `SANDBOX`). See [Authentication →](/v3.20/documentation/authentication)

## Response Format

Every response — success and error alike — uses the same top-level envelope.

```json Success — single resource theme={null}
{
  "success": true,
  "status": 200,
  "message": "Card retrieved",
  "data": {
    "cardId": "crd_01HXYZ5555ABCDEF1111",
    "status": "ACTIVE"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

```json Success — paginated list theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cards retrieved",
  "data": [ ... ],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

```json Error theme={null}
{
  "success": false,
  "status": 422,
  "message": "Cardholder KYC is not approved",
  "error": {
    "code": "CARDHOLDER_KYC_NOT_APPROVED",
    "detail": "The cardholder must have kycStatus APPROVED before a card can be issued"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

See [Error Handling →](/v3.20/documentation/errors) for the full error code catalogue.

## Pagination

List endpoints accept `limit` (default 20, max 100) and `offset` (default 0) query parameters. Use `pagination.hasMore` to detect additional pages:

```
GET /cardholders?limit=20&offset=0   → first page
GET /cardholders?limit=20&offset=20  → second page
GET /cardholders?limit=20&offset=40  → third page
```

## Rate Limits

1,000 requests per minute per API key (sliding window). Every response includes:

| Header                  | Description                              |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Your key's cap per minute                |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

Exceeding the limit returns `429 RATE_LIMITED`.

## Idempotency

For write operations, supply an `Idempotency-Key` header to safely retry without risk of duplicates. The key is valid for 24 hours. See [Authentication → Idempotency-Key](/v3.20/documentation/authentication#idempotency-key-header).

## API Versioning

This is version **3.20** of the FYATU CaaS API. The version is embedded in the URL prefix (`/api/v3.20/`). Breaking changes (field removals, semantic changes) are announced at least **90 days** in advance. Additive changes (new optional fields, new event types) may be introduced without notice.

***

## Endpoint Summary

### Cardholders

| Method  | Path                           | Scope               | Description                        |
| ------- | ------------------------------ | ------------------- | ---------------------------------- |
| `POST`  | `/cardholders`                 | `cardholders:write` | Create a cardholder (triggers KYC) |
| `GET`   | `/cardholders`                 | `cardholders:read`  | List cardholders                   |
| `GET`   | `/cardholders/{id}`            | `cardholders:read`  | Get a single cardholder            |
| `PATCH` | `/cardholders/{id}`            | `cardholders:write` | Update cardholder fields           |
| `POST`  | `/cardholders/{id}/suspend`    | `cardholders:write` | Suspend a cardholder               |
| `POST`  | `/cardholders/{id}/reactivate` | `cardholders:write` | Reactivate a suspended cardholder  |

### Cards

| Method | Path                    | Scope         | Description                                 |
| ------ | ----------------------- | ------------- | ------------------------------------------- |
| `POST` | `/cards`                | `cards:write` | Issue a card to an approved cardholder      |
| `GET`  | `/cards`                | `cards:read`  | List cards                                  |
| `GET`  | `/cards/{id}`           | `cards:read`  | Get a single card                           |
| `POST` | `/cards/{id}/fund`      | `cards:write` | Load funds from program ledger onto card    |
| `POST` | `/cards/{id}/unload`    | `cards:write` | Return funds from card to program ledger    |
| `POST` | `/cards/{id}/freeze`    | `cards:write` | Freeze a card (blocks new transactions)     |
| `POST` | `/cards/{id}/unfreeze`  | `cards:write` | Unfreeze a frozen card                      |
| `POST` | `/cards/{id}/terminate` | `cards:write` | Permanently terminate a card (irreversible) |

### Transactions

| Method | Path                 | Scope               | Description                        |
| ------ | -------------------- | ------------------- | ---------------------------------- |
| `GET`  | `/transactions`      | `transactions:read` | List transactions across all cards |
| `GET`  | `/transactions/{id}` | `transactions:read` | Get a single transaction           |

### Webhooks

| Method   | Path             | Scope            | Description                   |
| -------- | ---------------- | ---------------- | ----------------------------- |
| `POST`   | `/webhooks`      | `webhooks:write` | Create a webhook endpoint     |
| `GET`    | `/webhooks`      | `webhooks:read`  | List webhook endpoints        |
| `GET`    | `/webhooks/{id}` | `webhooks:read`  | Get a single webhook endpoint |
| `PATCH`  | `/webhooks/{id}` | `webhooks:write` | Update a webhook endpoint     |
| `DELETE` | `/webhooks/{id}` | `webhooks:write` | Delete a webhook endpoint     |

### Utility

| Method | Path    | Auth | Description                                        |
| ------ | ------- | ---- | -------------------------------------------------- |
| `GET`  | `/ping` | None | Health check — returns API version and environment |