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)
A SANDBOX API key with cardholders:write, cards:write, and transactions:read scopes
A programId (visible in the portal under Programs)

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.

Step 1 — Ping the API

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

cURL

curl https://api.fyatu.com/api/v3.20/ping

Response (200 OK)

{
  "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.

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"
  }'

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"

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"

Response (201 Created)

{
  "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. The CARDHOLDER_KYC_APPROVED webhook payload:

{
  "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

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

KYC approved response

{
  "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"
  }
}

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

Step 4 — Issue a Card

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

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"
  }'

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"

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'])

Response (201 Created)

{
  "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.

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"
  }'

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

Response (200 OK)

{
  "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

Set Up Webhooks

Subscribe to transaction events so your platform updates in real time — no polling needed.

Explore All Endpoints

Full API reference with request and response schemas for every endpoint.

Freeze and Unfreeze Cards

Temporarily block transactions — useful for suspicious activity or a lost card report.

Read Transactions

Query card transaction history with filters by card, cardholder, date, and status.

Getting Started

Concepts

Quickstart

Quickstart

Step 1 — Ping the API

Step 2 — Create a Cardholder

Step 3 — Wait for KYC Approval

Step 4 — Issue a Card

Step 5 — Fund the Card

Next Steps

Set Up Webhooks

Explore All Endpoints

Freeze and Unfreeze Cards

Read Transactions

​Quickstart

​Step 1 — Ping the API

​Step 2 — Create a Cardholder

​Step 3 — Wait for KYC Approval

​Step 4 — Issue a Card

​Step 5 — Fund the Card

​Next Steps

Set Up Webhooks

Explore All Endpoints

Freeze and Unfreeze Cards

Read Transactions

Quickstart

Step 1 — Ping the API

Step 2 — Create a Cardholder

Step 3 — Wait for KYC Approval

Step 4 — Issue a Card

Step 5 — Fund the Card

Next Steps