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

# Introduction

> FYATU CaaS API v3.20 — issue and manage virtual cards programmatically via a clean REST API with API key authentication.

# FYATU CaaS API v3.20

The FYATU Cards-as-a-Service (CaaS) API v3.20 lets you issue virtual Visa and Mastercard prepaid cards to your users at scale, directly from your server. No card industry experience required — you bring the users, we handle the card rails, compliance, and settlement.

## What You Can Build

<CardGroup cols={2}>
  <Card title="Cardholder Management" icon="users">
    Create cardholder profiles, trigger KYC, suspend fraudulent users, and reactivate them — all via API.
  </Card>

  <Card title="Card Issuance" icon="credit-card">
    Issue virtual cards in seconds. Fund, freeze, unfreeze, or terminate any card on demand.
  </Card>

  <Card title="Transaction Monitoring" icon="chart-line">
    Query real-time card transactions with merchant data, MCC codes, and authorization status.
  </Card>

  <Card title="Webhook Events" icon="bolt">
    Subscribe to 30+ event types — from `TRANSACTION_PROCESSED` to `CARDHOLDER_KYC_APPROVED` — and react in real time.
  </Card>
</CardGroup>

## How It Works

```
Your Platform                    FYATU CaaS API
─────────────────────────────────────────────────

1. Create cardholder             POST /cardholders
   (KYC triggered automatically)

2. Wait for KYC approval         CARDHOLDER_KYC_APPROVED webhook

3. Issue card                    POST /cards
   (zero balance, ready to fund)

4. Fund card                     POST /cards/{id}/fund
   (debits your program ledger)

5. Cardholder transacts          TRANSACTION_PROCESSED webhook
   (real-time Visa/Mastercard)

6. Unload or terminate           POST /cards/{id}/unload
   when done                     POST /cards/{id}/terminate
```

## Key Concepts

### API Keys

Authentication is done via API keys. Each key is bound to one environment (`LIVE` or `SANDBOX`) and carries specific scopes that control what the key can do. Create and manage keys in the [CaaS portal](https://platform.fyatu.com). See [Authentication](/v3.20/documentation/authentication).

### Environments

* **SANDBOX** — no real money, no real cards. Perfect for development and QA. KYC completes in seconds and card issuance is instant.
* **LIVE** — real card issuance, real transactions. Use only when your integration is fully tested.

Environments are fully isolated. A `SANDBOX` API key cannot read or write `LIVE` data and vice versa.

### Card Programs

Every cardholder and card belongs to a **card program** — a container you configure in the portal that sets the card network (Visa/Mastercard), currency, spending limits, and compliance rules. The API references programs by `programId`.

### Cardholders

A **cardholder** is the end-user who will hold and spend on a card. Cardholders must complete KYC (Know Your Customer) identity verification before a card can be issued to them. The `kycStatus` field tracks progress: `PENDING` → `APPROVED` (or `REJECTED`).

### The Program Ledger

Your program holds a pre-funded balance — the "program ledger" — that funds are drawn from when you load a card. When you call `POST /cards/{id}/fund`, money moves from the program ledger to the card. When you call `POST /cards/{id}/unload` or a card is terminated, the balance returns to the ledger. Monitor and top up your program balance in the portal.

### Response Envelope

Every API response uses a consistent shape:

```json Single resource theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": { ... },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

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

See [Error Handling](/v3.20/documentation/errors) for the full envelope specification and all error codes.

## Base URL

All v3.20 requests go to:

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

## API Surface

| Resource         | Endpoints                                                   | Scopes                                  |
| ---------------- | ----------------------------------------------------------- | --------------------------------------- |
| **Cardholders**  | Create, List, Get, Update, Suspend, Reactivate              | `cardholders:read`, `cardholders:write` |
| **Cards**        | Issue, List, Get, Fund, Unload, Freeze, Unfreeze, Terminate | `cards:read`, `cards:write`             |
| **Transactions** | List, Get                                                   | `transactions:read`                     |
| **Webhooks**     | Create, List, Get, Update, Delete                           | `webhooks:read`, `webhooks:write`       |

## Next Steps

<Steps>
  <Step title="Read the authentication guide">
    Learn how to create an API key, set its scopes, and send it with requests.
    [Authentication →](/v3.20/documentation/authentication)
  </Step>

  <Step title="Follow the quickstart">
    Create your first cardholder, wait for KYC, issue a card, and fund it in under 5 minutes.
    [Quickstart →](/v3.20/documentation/quickstart)
  </Step>

  <Step title="Set up webhooks">
    Subscribe to events so your platform reacts in real time — no polling needed.
    [Webhook Guide →](/v3.20/webhooks/signature-verification)
  </Step>
</Steps>