Skip to main content

​
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"
  }'
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"
  }'
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"
  }'
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_AUTHORIZED webhook with the merchant details and the amount reserved.

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