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

# Quickstart

> Create your first cardholder, wait for KYC approval, issue a card, and fund it — end to end in under 5 minutes.

# Quickstart

This guide takes you from zero to a funded, active virtual card in five steps. You'll need:

* A FYATU CaaS account (apply at [platform.fyatu.com](https://platform.fyatu.com))
* A SANDBOX API key with `cardholders:write`, `cards:write`, and `transactions:read` scopes
* A `programId` (visible in the portal under **Programs**)

<Info>
  Use your **SANDBOX** key for this guide. Sandbox operations are free, instant, and involve no real money or cards. KYC completes in a few seconds automatically.
</Info>

## Step 1 — Ping the API

Verify your setup by calling the health endpoint. No authentication required.

```bash cURL theme={null}
curl https://api.fyatu.com/api/v3.20/ping
```

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "pong",
  "data": {
    "version": "3.20",
    "environment": "SANDBOX"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

If you see this response, your network access to the API is working. Move on to Step 2.

## Step 2 — Create a Cardholder

A cardholder represents one of your end-users. KYC is triggered automatically on creation and runs asynchronously. In SANDBOX, approval happens within a few seconds.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.fyatu.com/api/v3.20/cardholders \
    -H "Authorization: Bearer $FYATU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "programId":   "prg_01HXYZ9876ABCDEF0000",
      "firstName":   "Jane",
      "lastName":    "Doe",
      "email":       "jane.doe@example.com",
      "phone":       "+12025551234",
      "dateOfBirth": "1992-03-20",
      "nationality": "US",
      "address": {
        "line1":      "456 Elm Street",
        "city":       "Austin",
        "state":      "Texas",
        "postalCode": "78701",
        "country":    "US"
      },
      "externalId":  "my-user-id-789"
    }'
  ```

  ```javascript Node.js theme={null}
  const resp = await fetch('https://api.fyatu.com/api/v3.20/cardholders', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FYATU_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      programId:   'prg_01HXYZ9876ABCDEF0000',
      firstName:   'Jane',
      lastName:    'Doe',
      email:       'jane.doe@example.com',
      phone:       '+12025551234',
      dateOfBirth: '1992-03-20',
      nationality: 'US',
      address: {
        line1:      '456 Elm Street',
        city:       'Austin',
        state:      'Texas',
        postalCode: '78701',
        country:    'US',
      },
      externalId: 'my-user-id-789',
    }),
  });

  const body = await resp.json();
  const cardholder = body.data;
  console.log('Cardholder ID:', cardholder.cardholderId);
  console.log('KYC Status:',   cardholder.kycStatus); // "PENDING"
  ```

  ```python Python theme={null}
  import os, requests

  resp = requests.post(
      'https://api.fyatu.com/api/v3.20/cardholders',
      headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
      json={
          'programId':   'prg_01HXYZ9876ABCDEF0000',
          'firstName':   'Jane',
          'lastName':    'Doe',
          'email':       'jane.doe@example.com',
          'phone':       '+12025551234',
          'dateOfBirth': '1992-03-20',
          'nationality': 'US',
          'address': {
              'line1':      '456 Elm Street',
              'city':       'Austin',
              'state':      'Texas',
              'postalCode': '78701',
              'country':    'US',
          },
          'externalId': 'my-user-id-789',
      },
  )

  body = resp.json()
  cardholder = body['data']
  print('Cardholder ID:', cardholder['cardholderId'])
  print('KYC Status:',   cardholder['kycStatus'])  # "PENDING"
  ```
</CodeGroup>

**Response (201 Created)**

```json theme={null}
{
  "success": true,
  "status": 201,
  "message": "Cardholder created",
  "data": {
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "programId":     "prg_01HXYZ9876ABCDEF0000",
    "firstName":     "Jane",
    "lastName":      "Doe",
    "email":         "jane.doe@example.com",
    "status":        "ACTIVE",
    "kycStatus":     "PENDING",
    "kycVerifiedAt": null,
    "environment":   "SANDBOX",
    "totalCards":    0,
    "createdAt":     "2026-05-22T10:00:00Z",
    "updatedAt":     "2026-05-22T10:00:00Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}
```

Save the `cardholderId` — you'll need it in Step 4.

## Step 3 — Wait for KYC Approval

KYC runs asynchronously after cardholder creation. In SANDBOX it completes within a few seconds.

**Option A — Webhook (recommended)**

Register a webhook that subscribes to `CARDHOLDER_KYC_APPROVED` and `CARDHOLDER_KYC_REJECTED`. You'll be notified as soon as the check completes. See [Webhook Signature Verification](/v3.20/webhooks/signature-verification).

The `CARDHOLDER_KYC_APPROVED` webhook payload:

```json theme={null}
{
  "event":       "CARDHOLDER_KYC_APPROVED",
  "eventId":     "evt_01HXY123456ABCDEF",
  "businessId":  "BUS1A2B3C4D5E6F",
  "environment": "SANDBOX",
  "timestamp":   "2026-05-22T10:00:05Z",
  "data": {
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "kycStatus":     "APPROVED",
    "kycVerifiedAt": "2026-05-22T10:00:05Z"
  }
}
```

**Option B — Poll the cardholder**

```bash theme={null}
curl https://api.fyatu.com/api/v3.20/cardholders/chl_01HXYZ1234ABCDEF5678 \
  -H "Authorization: Bearer $FYATU_API_KEY"
```

Keep polling until `kycStatus` is `APPROVED` (or `REJECTED`).

```json KYC approved response theme={null}
{
  "success": true,
  "status": 200,
  "message": "Cardholder retrieved",
  "data": {
    "cardholderId":  "chl_01HXYZ1234ABCDEF5678",
    "kycStatus":     "APPROVED",
    "kycVerifiedAt": "2026-05-22T10:00:05Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:06Z"
  }
}
```

<Warning>
  You cannot issue a card until `kycStatus` is `APPROVED`. If KYC is `REJECTED`, check `kycRejectionReason` and contact support if the rejection is unexpected.
</Warning>

## Step 4 — Issue a Card

With KYC approved, issue a virtual card to the cardholder.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.fyatu.com/api/v3.20/cards \
    -H "Authorization: Bearer $FYATU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "cardholderId": "chl_01HXYZ1234ABCDEF5678",
      "programId":    "prg_01HXYZ9876ABCDEF0000",
      "type":         "VIRTUAL"
    }'
  ```

  ```javascript Node.js theme={null}
  const cardResp = await fetch('https://api.fyatu.com/api/v3.20/cards', {
    method:  'POST',
    headers: {
      'Authorization': `Bearer ${process.env.FYATU_API_KEY}`,
      'Content-Type':  'application/json',
    },
    body: JSON.stringify({
      cardholderId: 'chl_01HXYZ1234ABCDEF5678',
      programId:    'prg_01HXYZ9876ABCDEF0000',
      type:         'VIRTUAL',
    }),
  });

  const { data: card } = await cardResp.json();
  console.log('Card ID:', card.cardId);
  console.log('Last 4:', card.last4);
  console.log('Status:', card.status); // "ACTIVE"
  ```

  ```python Python theme={null}
  card_resp = requests.post(
      'https://api.fyatu.com/api/v3.20/cards',
      headers={'Authorization': f'Bearer {os.environ["FYATU_API_KEY"]}'},
      json={
          'cardholderId': 'chl_01HXYZ1234ABCDEF5678',
          'programId':    'prg_01HXYZ9876ABCDEF0000',
          'type':         'VIRTUAL',
      },
  )
  card = card_resp.json()['data']
  print('Card ID:', card['cardId'])
  print('Last 4:', card['last4'])
  ```
</CodeGroup>

**Response (201 Created)**

```json theme={null}
{
  "success": true,
  "status": 201,
  "message": "Card issued",
  "data": {
    "cardId":       "crd_01HXYZ5555ABCDEF1111",
    "cardholderId": "chl_01HXYZ1234ABCDEF5678",
    "programId":    "prg_01HXYZ9876ABCDEF0000",
    "status":       "ACTIVE",
    "cardBrand":    "VISA",
    "maskedPan":    "**** **** **** 4242",
    "last4":        "4242",
    "expiryMonth":  5,
    "expiryYear":   2029,
    "currency":     "USD",
    "environment":  "SANDBOX",
    "createdAt":    "2026-05-22T10:00:10Z",
    "updatedAt":    "2026-05-22T10:00:10Z"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:10Z"
  }
}
```

The `CARD_ISSUED` webhook fires immediately after issuance. The card starts with **zero balance** — proceed to Step 5 to fund it.

## Step 5 — Fund the Card

Load \$50 from the program ledger onto the card. This debits the program balance and credits the card.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111/fund \
    -H "Authorization: Bearer $FYATU_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: fund-crd01HXYZ5555-order-001" \
    -d '{
      "amount": 50.00,
      "note":   "Initial load"
    }'
  ```

  ```javascript Node.js theme={null}
  const fundResp = await fetch(
    'https://api.fyatu.com/api/v3.20/cards/crd_01HXYZ5555ABCDEF1111/fund',
    {
      method:  'POST',
      headers: {
        'Authorization':  `Bearer ${process.env.FYATU_API_KEY}`,
        'Content-Type':   'application/json',
        'Idempotency-Key': 'fund-crd01HXYZ5555-order-001',
      },
      body: JSON.stringify({ amount: 50.00, note: 'Initial load' }),
    },
  );

  const { data } = await fundResp.json();
  console.log('Loaded cents:',         data.amountCents);       // 5000
  console.log('Program balance after:', data.balanceAfterCents); // program cents remaining
  ```
</CodeGroup>

**Response (200 OK)**

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Card funded successfully",
  "data": {
    "cardId":              "crd_01HXYZ5555ABCDEF1111",
    "amountCents":         5000,
    "currency":            "USD",
    "balanceAfterCents":   5000,
    "ledgerTransactionId": "ltx_01HXYZ9999ABCDEF2222",
    "card": {
      "cardId":      "crd_01HXYZ5555ABCDEF1111",
      "status":      "ACTIVE",
      "maskedPan":   "**** **** **** 4242",
      "last4":       "4242",
      "currency":    "USD",
      "environment": "SANDBOX"
    }
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:15Z"
  }
}
```

**Done.** Your cardholder now has an active virtual card with a \$50 balance.

When your cardholder makes a purchase, you will receive a `TRANSACTION_PROCESSED` webhook (`status: COMPLETED`) with the merchant details and the amount charged.

## Next Steps

<CardGroup cols={2}>
  <Card title="Set Up Webhooks" icon="bolt" href="/v3.20/webhooks/signature-verification">
    Subscribe to transaction events so your platform updates in real time — no polling needed.
  </Card>

  <Card title="Explore All Endpoints" icon="square-terminal" href="/v3.20/api-reference/overview">
    Full API reference with request and response schemas for every endpoint.
  </Card>

  <Card title="Freeze and Unfreeze Cards" icon="snowflake" href="/v3.20/api-reference/cards/freeze">
    Temporarily block transactions — useful for suspicious activity or a lost card report.
  </Card>

  <Card title="Read Transactions" icon="list" href="/v3.20/api-reference/transactions/list">
    Query card transaction history with filters by card, cardholder, date, and status.
  </Card>
</CardGroup>