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

> Complete REST API reference for Fyatu v3 — card issuing, payment collections, payouts, refunds, and webhook configuration endpoints.

This section provides detailed documentation for every V3 endpoint, including request/response schemas, parameters, and examples.

## Base URL

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

## Authentication

V3 uses JWT Bearer tokens. First obtain a token, then include it in all requests:

```bash theme={null}
# Step 1: Get token
curl -X POST https://api.fyatu.com/api/v3/auth/token \
  -H "Content-Type: application/json" \
  -d '{"appId": "YOUR_APP_ID", "secretKey": "YOUR_SECRET", "grantType": "client_credentials"}'

# Step 2: Use token
curl -X GET https://api.fyatu.com/api/v3/collections \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

## Request Format

* All requests use **JSON** body format
* Set `Content-Type: application/json` for POST/PUT/PATCH requests
* All timestamps are in **ISO 8601** format

## Response Format

All V3 responses follow this structure:

<CodeGroup>
  ```json Success (2xx) theme={null}
  {
    "success": true,
    "status": 200,
    "message": "Operation completed successfully",
    "data": { ... },
    "meta": {
      "requestId": "req_xxxxxxxxxxxx",
      "timestamp": "2026-01-05T10:30:00+00:00"
    }
  }
  ```

  ```json Error (4xx/5xx) theme={null}
  {
    "success": false,
    "status": 400,
    "message": "Error description",
    "error": {
      "code": "ERROR_CODE",
      "details": [...]
    },
    "meta": {
      "requestId": "req_xxxxxxxxxxxx",
      "timestamp": "2026-01-05T10:30:00+00:00"
    }
  }
  ```
</CodeGroup>

## Available Endpoints

### Authentication

Obtain and manage JWT access tokens.

| Method | Endpoint        | Description            |
| ------ | --------------- | ---------------------- |
| POST   | `/auth/token`   | Generate access token  |
| POST   | `/auth/refresh` | Refresh existing token |
| POST   | `/auth/revoke`  | Revoke a token         |

### Account

Manage your business account, wallet, and fees.

| Method | Endpoint                      | Description                 |
| ------ | ----------------------------- | --------------------------- |
| GET    | `/account/pricing`            | Get applicable fees         |
| GET    | `/account/wallet`             | Get wallet balances         |
| GET    | `/account/transactions`       | List account transactions   |
| GET    | `/account/withdrawals`        | Get withdrawal history      |
| POST   | `/account/deposit-address`    | Generate deposit address    |
| POST   | `/account/withdrawal-address` | Register withdrawal address |

### Collections

Accept payments from customers.

| Method | Endpoint                   | Description             |
| ------ | -------------------------- | ----------------------- |
| POST   | `/collections`             | Create checkout session |
| GET    | `/collections`             | List collections        |
| GET    | `/collections/{id}`        | Get collection details  |
| POST   | `/collections/{id}/refund` | Issue a refund          |

### Refunds

Manage refunds for collections.

| Method | Endpoint   | Description  |
| ------ | ---------- | ------------ |
| GET    | `/refunds` | List refunds |

### Payouts

Send money to Fyatu account holders.

| Method | Endpoint               | Description              |
| ------ | ---------------------- | ------------------------ |
| GET    | `/accounts/{clientId}` | Verify recipient account |
| POST   | `/payouts`             | Create payout            |
| GET    | `/payouts`             | List payouts             |
| GET    | `/payouts/{id}`        | Get payout details       |

## Error Codes

| Code                       | HTTP | Description                   |
| -------------------------- | ---- | ----------------------------- |
| `AUTH_TOKEN_MISSING`       | 401  | No token provided             |
| `AUTH_TOKEN_INVALID`       | 401  | Token is malformed or expired |
| `AUTH_TOKEN_EXPIRED`       | 401  | Token has expired             |
| `AUTH_INVALID_CREDENTIALS` | 401  | Invalid appId or secretKey    |
| `AUTH_APP_INACTIVE`        | 401  | App is not active             |
| `AUTH_SCOPE_DENIED`        | 403  | Token lacks required scope    |
| `VALIDATION_ERROR`         | 400  | Request validation failed     |
| `RESOURCE_NOT_FOUND`       | 404  | Resource not found            |
| `INSUFFICIENT_BALANCE`     | 402  | Wallet balance too low        |
| `DUPLICATE_REFERENCE`      | 409  | Reference already used        |
| `RATE_LIMIT_EXCEEDED`      | 429  | Too many requests             |
| `INTERNAL_ERROR`           | 500  | Server error                  |

## Rate Limits

| Endpoint Category | Rate Limit  |
| ----------------- | ----------- |
| Authentication    | 10 req/min  |
| Read operations   | 100 req/min |
| Write operations  | 30 req/min  |

<Warning>
  Exceeding rate limits returns `429 Too Many Requests`. Implement exponential backoff in retry logic.
</Warning>