API Overview

Base URL

https://api.tokencashflow.com

All endpoints are versioned under /v1/.

Versioning

The current API version is v1. Breaking changes will be released under a new version prefix (e.g. /v2/). The current version will continue to be supported for a deprecation window after any new version is released.

Request format

• All requests must include Content-Type: application/json when sending a body
• All timestamps must be in ISO 8601 format with UTC timezone: "2026-05-16T12:00:00Z"
• Decimal amounts are sent and received as strings in JSON to avoid floating-point precision loss (e.g. "amount_usd": "150.00")
• UUIDs are lowercase hyphenated strings

Response envelope

Every API response — success or error — is wrapped in a standard envelope:

Success:

{
  "success": true,
  "data": {
    "id": "9f1b2c3d-...",
    "status": "awaiting_selection"
  },
  "error": null
}

Error:

{
  "success": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Insufficient account balance.",
    "details": {}
  }
}

The details field may contain field-level validation errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "amount_usd": ["Value error, amount_usd must be greater than 0."],
      "redirect_url": ["Value error, redirect_url must use HTTPS."]
    }
  }
}

Pagination

List endpoints (GET /v1/payments, GET /v1/webhooks/deliveries, GET /v1/withdrawals, etc.) return paginated responses. Most use this shape:

Query parameters:

Parameter	Default	Max	Description
page or page_size	1 / 20	—	Page number / items per page (1-indexed; payments and webhooks use per_page, withdrawals and API keys use page_size)

Response (payments example):

{
  "success": true,
  "data": {
    "total": 453,
    "page": 1,
    "page_size": 20,
    "total_pages": 23,
    "payments": [...]
  }
}

The pagination metadata (total, page, page_size/per_page, total_pages) sits alongside the items array, not in a nested pagination object.

Authentication

Credential type	Header	Accepted on
API key	X-API-Key: tcf_live_...	Payments API, Withdrawals API

Unauthenticated public endpoints (payment page data, status polling, payer confirm, rate and fee lookups under /v1/pay/...) do not require any header. See Authentication Reference for full details.

Maintenance mode

During platform maintenance the API returns a 503 with error code MAINTENANCE. Maintenance can affect all routes or just deposit (/v1/pay*, /v1/payments*) or withdrawal (/v1/withdrawals*) routes. GET /health and GET /v1/brand always remain available.

HTTPS only

All API traffic is served over HTTPS. HTTP requests are not accepted. Webhook endpoint URLs must also use HTTPS.

CORS

CORS is restricted to known TokenCashFlow frontend origins. Third-party browser-based JavaScript cannot call the API directly — use server-side requests with API keys.

Timestamps & decimals

• All timestamps are UTC, ISO 8601 (e.g. "2026-05-16T12:00:00Z" or with microseconds/timezone offset).
• Decimal amounts are serialized as JSON strings to avoid floating-point precision loss (e.g. "amount_usd": "150.00").
• UUIDs are lowercase hyphenated strings.