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. Minimum: 1.00. No maximum.
description	string	No	Shown to the payer on the payment page. Max 500 characters.
redirect_url	string	No	HTTPS URL to redirect the payer to after the payment reaches COMPLETED.
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
payment_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	Payment amount
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
EXPIRED_SELECTION	Chain selection window expired; payer can return and reselect at current market rate
CONFIRMING	Full amount received; waiting for required block confirmations
CONFIRMED	Confirmations reached; sweep in progress
COMPLETED	Sweep done and merchant account credited
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

Payments never expire globally. Only the chain selection window (selection_expires_at) expires. 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 → Enabled 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_...

Listing and filtering payments

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

Query parameters:

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

Response:

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

Fetching a single payment

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

Returns full payment detail including:

• All state transition timestamps
• Locked rate and required crypto amount (after payer confirms)
• Received amounts
• Fee breakdown
• Linked sweep and transaction records

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, expires_at, selection_expires_at, total_received_crypto, required_crypto_amount.

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