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": {
    "payment_id": "9f1b2c3d-...",
    "status": "AWAITING_SELECTION"
  },
  "error": null
}

Error:

{
  "success": false,
  "data": null,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "Your account balance is insufficient for this withdrawal.",
    "details": {}
  }
}

The details field may contain field-level validation errors:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "details": {
      "amount_usd": ["amount_usd must be at least $1.00."],
      "redirect_url": ["redirect_url must start with https://"]
    }
  }
}

Pagination

All list endpoints (GET /v1/payments, GET /v1/webhooks/deliveries, etc.) return paginated responses.

Query parameters:

Parameter	Default	Max	Description
page	1	—	Page number (1-indexed)
per_page	20	100	Items per page

Response:

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

Authentication

All merchant endpoints require authentication. See Authentication Reference for full details.

Credential type	Header
API key	X-API-Key: tcf_live_...
Session token	Authorization: Bearer {token}

Unauthenticated public endpoints (e.g. payment status polling at GET /v1/pay/{payment_id}/status) do not require any header.

HTTPS only

All API traffic is served over HTTPS. HTTP requests are not accepted.

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

All stored and returned timestamps are in UTC. The API always returns timestamps in ISO 8601 format with explicit Z suffix (e.g. "2026-05-16T12:00:00Z").