Skip to main content

​
Integration Flow

​
1) Create Quote

Use exactly one amount mode (crypto_amount or fiat_amount). 
curl -X POST "$BASE_URL/quotes" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -d '{
    "crypto_currency": "usdt",
    "crypto_amount": "100.00",
    "network": "trc20"
  }'
Use the quote before expires_at.

​
2) Create Transaction

Always send:
  • merchant_reference (canonical partner key)
  • Idempotency-Key (safe retries)
Use either:
  • Quote mode: quote_id
  • Direct mode: fiat_amount + crypto_currency + network
curl -X POST "$BASE_URL/transactions" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $API_KEY" \
  -H "Idempotency-Key: tx-create-2026-0001" \
  -d '{
    "quote_id": "9f8ad58e-f8d5-4e4f-b3f2-f44eaf8f95d1",
    "network": "trc20",
    "merchant_reference": "order-4551",
    "merchant_id": "mrc_001",
    "terminal_id": "term_01"
  }'
Persist:
  • id
  • merchant_reference
  • deposit_address
  • expires_at
  • rate
  • amount
  • crypto_amount
  • crypto_currency
  • network

​
3) Handle Timeouts and Recovery

If create request times out, recover by reference: 
curl -X GET "$BASE_URL/transactions/reference/order-4551" \
  -H "X-API-KEY: $API_KEY"

​
4) Process Webhooks

  • Verify X-CW-Webhook-Signature.
  • Deduplicate by webhook id.
  • Upsert transaction status only when state progression is valid for your system.
For recovery:
  • GET /webhooks/events
  • GET /webhooks/events/{event_id}
  • POST /webhooks/events/{event_id}/replay

​
5) Reconcile Periodically

Use list + revenue endpoints with fixed windows and cursors:
  • GET /transactions
  • GET /revenue
Do not rely on webhook delivery timing as the only source of truth.

​
6) Test Lifecycle Progression In Staging

Use the standalone sandbox simulator to trigger partner lifecycle events against a known transaction: You must first create the transaction and then pass the returned transaction id as transaction_id. 
curl -X POST "https://dev.cashweb.cash/api/v1/partner/sandbox/simulate" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $SANDBOX_API_KEY" \
  -d '{
    "transaction_id": "01917f00-7b4c-7f56-8a2b-15998d58c9f3",
    "event": "deposit.confirmed"
  }'