TokenCashFlow Docs

Appearance

Quickstart Guide ​

Get your first crypto payment running in under 10 minutes.

What you can do with TokenCashFlow ​

TokenCashFlow is a multi-chain crypto payment service provider. With a single API integration you can accept any supported cryptocurrency from your customers, automatically convert it to USDT if desired, and receive real-time webhook notifications on every payment event — all without touching a blockchain yourself.

Prerequisites ​

  • A registered TokenCashFlow merchant account with at least Basic KYC approved
  • An API key (see Step 1)
  • A public HTTPS URL to receive webhooks (optional for testing)

Step 1 — Create an API key ​

  1. Log in to the TokenCashFlow Client Portal
  2. Navigate to Dashboard → API Keys
  3. Click New API Key, enter a label (e.g. production-server), and click Create
  4. Copy the full key immediately — it is shown only once

Your key format: tcf_live_ followed by random URL-safe characters (~41 characters total).

Step 2 — Create your first payment ​

Send a POST request to /v1/payments with your API key:

bash
curl -X POST https://api.tokencashflow.com/v1/payments \
  -H "X-API-Key: tcf_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_usd": 50.00,
    "description": "Order #1001",
    "redirect_url": "https://yourstore.com/thank-you"
  }'

Response (201 Created):

json
{
  "success": true,
  "data": {
    "id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "awaiting_selection",
    "amount_usd": "50.00",
    "description": "Order #1001",
    "pay_url": "https://app.tokencashflow.com/pay/9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "fee_payer": "user",
    "selection_expires_at": null,
    "created_at": "2026-05-16T12:00:00Z"
  },
  "error": null
}

The pay_url is the payment page your customer visits. Payment identifiers are returned as id in API responses and as payment_id inside webhook payloads.

Redirect your customer to the pay_url from Step 2. TokenCashFlow handles everything on that page:

  • Crypto selector (only cryptos you've enabled for your account)
  • Live exchange rate display (refreshed every 10 seconds)
  • Rate lock when the customer confirms their token
  • QR code and wallet address display
  • Real-time payment status updates (polled every 5 seconds)
  • Automatic redirect to your redirect_url after payment completes (5-second countdown)

Step 4 — Receive the webhook ​

When the payment reaches completed status, TokenCashFlow sends an HTTP POST to your configured webhook URL:

json
{
  "event": "payment.completed",
  "timestamp": "2026-05-16T12:05:00.123456+00:00",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "completed",
    "amount_usd": "50.00",
    "received_crypto": "0.025000000000000000",
    "crypto_symbol": "ETH",
    "crypto_name": "Ethereum",
    "chain": "eth",
    "locked_rate_usd": "2000.00",
    "fee_payer": "user",
    "fees": {
      "service_fee_usd": "0.25",
      "conversion_fee_usd": "1.00"
    },
    "net_amount_usd": "48.75",
    "selection_expires_at": null,
    "created_at": "2026-05-16T12:00:00Z",
    "completed_at": "2026-05-16T12:05:00Z",
    "redirect_url": "https://yourstore.com/thank-you"
  }
}

Always verify the signature on every webhook. See the Signature Verification guide.

Next steps ​

TokenCashFlow Documentation