Creating Payments

POST /v1/payments

Create a new payment request. Requires Basic KYC and an API key.

Request

POST https://api.tokencashflow.com/v1/payments
X-API-Key: tcf_live_...
Content-Type: application/json

Request body

Field	Type	Required	Description
amount_usd	decimal	Yes	Payment amount in USD. Must be greater than 0. The platform may enforce configurable global / per-token min/max limits.
description	string	No	Shown to the payer on the payment page. Max 150 characters.
redirect_url	string	No	HTTPS URL to redirect the payer to after the payment completes. Max 2048 characters.
allowed_token_ids	array of UUIDs	No	Restrict the payer to a subset of your enabled tokens. Defaults to your full enabled set. Token UUIDs are available from GET /v1/payments/tokens.

Example request:

curl -X POST https://api.tokencashflow.com/v1/payments \
  -H "X-API-Key: tcf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 150.00,
    "description": "Invoice #INV-2026-042",
    "redirect_url": "https://yourstore.com/order/complete?ref=INV-2026-042"
  }'

Response (201 Created)

Field	Type	Description
id	UUID	Unique payment identifier
pay_url	string	The payment page URL to share with your customer
status	string	Always awaiting_selection on creation
amount_usd	decimal (string)	Payment amount
fee_payer	string	Who absorbs fees — user (you) or payer (customer); snapshotted from your payment settings
selection_expires_at	ISO 8601 or null	Null on creation; set when payer confirms a token
created_at	ISO 8601	Creation timestamp (UTC)

Payment status reference

Status	Description
awaiting_selection	Payer has not selected a crypto yet — no countdown
awaiting_payment	Payer confirmed crypto and rate; selection_expires_at countdown running
partially_paid	Some funds received; payer can top up before selection window expires
confirming	Required amount received; waiting for required block confirmations
confirmed	Confirmations reached; sweep in progress
completed	Sweep done and merchant account credited
expired_selection	Chain selection window expired; payer can return and reselect at current market rate
blacklisted	Sender wallet address is on the platform blacklist
sweep_failed	Automated sweep from payment wallet failed; admin intervention required
failed	System error; requires investigation

Status values are always lowercase snake_case.

Only the chain selection window expires. Once the payer confirms a token, selection_expires_at starts a countdown (typically 30–60 minutes). expired_selection is fully recoverable — the payer can always return to the payment link and reselect.

Customising the allowed crypto list

By default, every payment offers all cryptos you have enabled in Dashboard → Payment Settings (an empty enabled list means all active tokens).

To restrict a specific payment to certain tokens, pass allowed_token_ids:

{
  "amount_usd": 100.00,
  "allowed_token_ids": [
    "a1b2c3d4-...",  // ETH on Ethereum
    "e5f6a7b8-..."   // USDT on Ethereum
  ]
}

Retrieve available token UUIDs from:

GET /v1/payments/tokens
X-API-Key: tcf_live_...

You can also manage your default enabled-token set and the fee payer option via the API:

GET /v1/payments/settings
PUT /v1/payments/settings     {"fee_payer": "user" | "payer", "enabled_token_ids": [...]}

Listing and filtering payments

GET /v1/payments
X-API-Key: tcf_live_...

Query parameters:

Parameter	Type	Description
status	string	Filter by status (lowercase, e.g. completed, awaiting_payment)
date_from	ISO 8601 date	Only payments created on or after this date (UTC)
date_to	ISO 8601 date	Only payments created on or before this date (UTC)
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 20, max: 100)

Response:

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

Fetching a single payment

GET /v1/payments/{payment_id}
X-API-Key: tcf_live_...

Returns full payment detail including:

• All state transition timestamps (awaiting_payment_at, partially_paid_at, confirming_at, confirmed_at, completed_at)
• Locked rate and required crypto amount (after payer confirms)
• Received amounts and fee breakdown
• The on-chain transactions received for this payment

Unauthenticated status polling

The payer's payment page polls this endpoint every 5 seconds. No authentication required:

GET /v1/pay/{payment_id}/status

Returns only safe public fields: status, total_received_crypto, required_crypto_amount, selection_expires_at, confirmations_received, confirmations_required, redirect_url.

selection_expires_at is null until the payer confirms a token selection; once set, this controls the countdown timer on the payment page.