API Reference

This section provides detailed documentation for every V3 endpoint, including request/response schemas, parameters, and examples.

Base URL

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

Authentication

V3 uses JWT Bearer tokens. First obtain a token, then include it in all requests:

# Step 1: Get token
curl -X POST https://api.fyatu.com/api/v3/auth/token \
  -H "Content-Type: application/json" \
  -d '{"appId": "YOUR_APP_ID", "secretKey": "YOUR_SECRET", "grantType": "client_credentials"}'

# Step 2: Use token
curl -X GET https://api.fyatu.com/api/v3/collections \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Request Format

All requests use JSON body format
Set Content-Type: application/json for POST/PUT/PATCH requests
All timestamps are in ISO 8601 format

Response Format

All V3 responses follow this structure:

{
  "success": true,
  "status": 200,
  "message": "Operation completed successfully",
  "data": { ... },
  "meta": {
    "requestId": "req_xxxxxxxxxxxx",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

{
  "success": false,
  "status": 400,
  "message": "Error description",
  "error": {
    "code": "ERROR_CODE",
    "details": [...]
  },
  "meta": {
    "requestId": "req_xxxxxxxxxxxx",
    "timestamp": "2026-01-05T10:30:00+00:00"
  }
}

Available Endpoints

Authentication

Obtain and manage JWT access tokens.

Method	Endpoint	Description
POST	`/auth/token`	Generate access token
POST	`/auth/refresh`	Refresh existing token
POST	`/auth/revoke`	Revoke a token

Account

Manage your business account, wallet, and fees.

Method	Endpoint	Description
GET	`/account/pricing`	Get applicable fees
GET	`/account/wallet`	Get wallet balances
GET	`/account/transactions`	List account transactions
GET	`/account/withdrawals`	Get withdrawal history
POST	`/account/deposit-address`	Generate deposit address
POST	`/account/withdrawal-address`	Register withdrawal address

Collections

Accept payments from customers.

Method	Endpoint	Description
POST	`/collections`	Create checkout session
GET	`/collections`	List collections
GET	`/collections/{id}`	Get collection details
POST	`/collections/{id}/refund`	Issue a refund

Refunds

Manage refunds for collections.

Method	Endpoint	Description
GET	`/refunds`	List refunds

Payouts

Send money to Fyatu account holders.

Method	Endpoint	Description
GET	`/accounts/{clientId}`	Verify recipient account
POST	`/payouts`	Create payout
GET	`/payouts`	List payouts
GET	`/payouts/{id}`	Get payout details

Error Codes

Code	HTTP	Description
`AUTH_TOKEN_MISSING`	401	No token provided
`AUTH_TOKEN_INVALID`	401	Token is malformed or expired
`AUTH_TOKEN_EXPIRED`	401	Token has expired
`AUTH_INVALID_CREDENTIALS`	401	Invalid appId or secretKey
`AUTH_APP_INACTIVE`	401	App is not active
`AUTH_SCOPE_DENIED`	403	Token lacks required scope
`VALIDATION_ERROR`	400	Request validation failed
`RESOURCE_NOT_FOUND`	404	Resource not found
`INSUFFICIENT_BALANCE`	402	Wallet balance too low
`DUPLICATE_REFERENCE`	409	Reference already used
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limits

Endpoint Category	Rate Limit
Authentication	10 req/min
Read operations	100 req/min
Write operations	30 req/min

Exceeding rate limits returns 429 Too Many Requests. Implement exponential backoff in retry logic.

Overview

Authentication

Account

Collections

Payouts

Cardholders

Cards

Base URL

Authentication

Request Format

Response Format

Available Endpoints

Authentication

Account

Collections

Refunds

Payouts

Error Codes

Rate Limits

​Base URL

​Authentication

​Request Format

​Response Format

​Available Endpoints

​Authentication

​Account

​Collections

​Refunds

​Payouts

​Error Codes

​Rate Limits

Base URL

Authentication

Request Format

Response Format

Available Endpoints

Authentication

Account

Collections

Refunds

Payouts

Error Codes

Rate Limits