API Reference — v3.20

Base URL

All v3.20 requests go to:

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

Request Format

Body: JSON — set Content-Type: application/json on all write requests.
Timestamps: ISO 8601 (2026-05-22T10:00:00Z) or YYYY-MM-DD where noted.
Amounts in requests: Full currency units (e.g. 50.00 = $50.00).
Amounts in responses: Always in cents as int64 (e.g. amountCents: 5000 = $50.00).

Authentication

All endpoints require an API key passed as a Bearer token:

Authorization: Bearer fyatu_live_abc123def456...

Keys are environment-scoped (LIVE or SANDBOX). See Authentication →

Response Format

Every response — success and error alike — uses the same top-level envelope.

Success — single resource

{
  "success": true,
  "status": 200,
  "message": "Card retrieved",
  "data": {
    "cardId": "crd_01HXYZ5555ABCDEF1111",
    "status": "ACTIVE"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}

Success — paginated list

{
  "success": true,
  "status": 200,
  "message": "Cards retrieved",
  "data": [ ... ],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 0,
    "hasMore": true
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}

Error

{
  "success": false,
  "status": 422,
  "message": "Cardholder KYC is not approved",
  "error": {
    "code": "CARDHOLDER_KYC_NOT_APPROVED",
    "detail": "The cardholder must have kycStatus APPROVED before a card can be issued"
  },
  "meta": {
    "requestId": "req_01HXY123456ABCDEF",
    "platform": "Fyatu CaaS",
    "timestamp": "2026-05-22T10:00:00Z"
  }
}

See Error Handling → for the full error code catalogue.

Pagination

List endpoints accept limit (default 20, max 100) and offset (default 0) query parameters. Use pagination.hasMore to detect additional pages:

GET /cardholders?limit=20&offset=0   → first page
GET /cardholders?limit=20&offset=20  → second page
GET /cardholders?limit=20&offset=40  → third page

Rate Limits

1,000 requests per minute per API key (sliding window). Every response includes:

Header	Description
`X-RateLimit-Limit`	Your key’s cap per minute
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

Exceeding the limit returns 429 RATE_LIMITED.

Idempotency

For write operations, supply an Idempotency-Key header to safely retry without risk of duplicates. The key is valid for 24 hours. See Authentication → Idempotency-Key.

API Versioning

This is version 3.20 of the FYATU CaaS API. The version is embedded in the URL prefix (/api/v3.20/). Breaking changes (field removals, semantic changes) are announced at least 90 days in advance. Additive changes (new optional fields, new event types) may be introduced without notice.

Endpoint Summary

Cardholders

Method	Path	Scope	Description
`POST`	`/cardholders`	`cardholders:write`	Create a cardholder (triggers KYC)
`GET`	`/cardholders`	`cardholders:read`	List cardholders
`GET`	`/cardholders/{id}`	`cardholders:read`	Get a single cardholder
`PATCH`	`/cardholders/{id}`	`cardholders:write`	Update cardholder fields
`POST`	`/cardholders/{id}/suspend`	`cardholders:write`	Suspend a cardholder
`POST`	`/cardholders/{id}/reactivate`	`cardholders:write`	Reactivate a suspended cardholder

Cards

Method	Path	Scope	Description
`POST`	`/cards`	`cards:write`	Issue a card to an approved cardholder
`GET`	`/cards`	`cards:read`	List cards
`GET`	`/cards/{id}`	`cards:read`	Get a single card
`POST`	`/cards/{id}/fund`	`cards:write`	Load funds from program ledger onto card
`POST`	`/cards/{id}/unload`	`cards:write`	Return funds from card to program ledger
`POST`	`/cards/{id}/freeze`	`cards:write`	Freeze a card (blocks new transactions)
`POST`	`/cards/{id}/unfreeze`	`cards:write`	Unfreeze a frozen card
`POST`	`/cards/{id}/terminate`	`cards:write`	Permanently terminate a card (irreversible)

Transactions

Method	Path	Scope	Description
`GET`	`/transactions`	`transactions:read`	List transactions across all cards
`GET`	`/transactions/{id}`	`transactions:read`	Get a single transaction

Webhooks

Method	Path	Scope	Description
`POST`	`/webhooks`	`webhooks:write`	Create a webhook endpoint
`GET`	`/webhooks`	`webhooks:read`	List webhook endpoints
`GET`	`/webhooks/{id}`	`webhooks:read`	Get a single webhook endpoint
`PATCH`	`/webhooks/{id}`	`webhooks:write`	Update a webhook endpoint
`DELETE`	`/webhooks/{id}`	`webhooks:write`	Delete a webhook endpoint

Utility

Method	Path	Auth	Description
`GET`	`/ping`	None	Health check — returns API version and environment

Getting Started

Payments

Cardholders

Cards

API Reference Overview

API Reference — v3.20

Base URL

Request Format

Authentication

Response Format

Rate Limits

Idempotency

API Versioning

Endpoint Summary

Cardholders

Cards

Transactions

Webhooks

Utility

​API Reference — v3.20

​Base URL

​Request Format

​Authentication

​Response Format

​Pagination

​Rate Limits

​Idempotency

​API Versioning

​Endpoint Summary

​Cardholders

​Cards

​Transactions

​Webhooks

​Utility

API Reference — v3.20

Base URL

Request Format

Authentication

Response Format

Pagination

Rate Limits

Idempotency

API Versioning

Endpoint Summary

Cardholders

Cards

Transactions

Webhooks

Utility