TokenCashFlow Docs

Appearance

Webhook Events Reference ​

Payment events ​

payment.created ​

Fired when a merchant creates a payment request.

json
{
  "event": "payment.created",
  "timestamp": "2026-05-16T12:00:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "AWAITING_SELECTION",
    "amount_usd": 150.00,
    "description": "Order #1001",
    "expires_at": "2026-05-16T13:00:00Z",
    "created_at": "2026-05-16T12:00:00Z"
  }
}

payment.awaiting ​

Fired when the payer confirms their crypto selection and the rate is locked. The payment is now waiting for an on-chain transaction. A selection_expires_at countdown starts.

json
{
  "event": "payment.awaiting",
  "timestamp": "2026-05-16T12:01:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "AWAITING_PAYMENT",
    "crypto_symbol": "ETH",
    "chain": "ethereum",
    "locked_rate_usd": 2000.00,
    "required_crypto_amount": "0.075000000000000000",
    "wallet_address": "0xpaymentwallet...",
    "selection_expires_at": "2026-05-16T12:31:00Z",
    "locked_at": "2026-05-16T12:01:00Z"
  }
}

payment.partial ​

Fired when a transaction is detected at the payment wallet but the received amount is less than required.

json
{
  "event": "payment.partial",
  "timestamp": "2026-05-16T12:03:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "PARTIALLY_PAID",
    "received_crypto": "0.030000000000000000",
    "required_crypto_amount": "0.075000000000000000",
    "remaining_crypto": "0.045000000000000000",
    "received_usd": 60.00,
    "crypto_symbol": "ETH",
    "chain": "ethereum"
  }
}

payment.confirming ​

Fired when the full required amount has been received and the payment is waiting for block confirmations.

json
{
  "event": "payment.confirming",
  "timestamp": "2026-05-16T12:04:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "CONFIRMING",
    "received_crypto": "0.075000000000000000",
    "crypto_symbol": "ETH",
    "chain": "ethereum",
    "required_confirmations": 12,
    "current_confirmations": 3
  }
}

payment.completed ​

Fired when the payment is fully confirmed and funds have been swept and settled. This is the primary event to trigger order fulfilment.

json
{
  "event": "payment.completed",
  "timestamp": "2026-05-16T12:05:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "COMPLETED",
    "amount_usd": 150.00,
    "received_crypto": "0.075000000000000000",
    "crypto_symbol": "ETH",
    "chain": "ethereum",
    "locked_rate_usd": 2000.00,
    "fees": {
      "service_fee_usd": 0.75,
      "conversion_fee_usd": 1.50
    },
    "net_amount_usd": 147.75,
    "completed_at": "2026-05-16T12:05:00Z"
  }
}

payment.expired_selection ​

Fired when the chain selection window expires. The payer can return to the payment page and reselect a token. No funds are lost — any partial payments already received are preserved.

json
{
  "event": "payment.expired_selection",
  "timestamp": "2026-05-16T12:31:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "EXPIRED_SELECTION",
    "crypto_symbol": "ETH",
    "chain": "ethereum",
    "total_received_crypto": "0.030000000000000000",
    "received_usd": 60.00,
    "remaining_usd": 90.00,
    "expired_at": "2026-05-16T12:31:00Z"
  }
}

total_received_crypto and received_usd are 0 / 0.00 if the selection expired with no prior partial payment.

payment.reselected ​

Fired when the payer reselects a token after EXPIRED_SELECTION. A new rate is locked and a new selection window starts.

json
{
  "event": "payment.reselected",
  "timestamp": "2026-05-16T12:45:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "AWAITING_PAYMENT",
    "crypto_symbol": "ETH",
    "chain": "ethereum",
    "locked_rate_usd": 2100.00,
    "required_crypto_amount": "0.042857142857142857",
    "wallet_address": "0xpaymentwallet...",
    "selection_expires_at": "2026-05-16T13:15:00Z",
    "locked_at": "2026-05-16T12:45:00Z"
  }
}

payment.blacklisted ​

Fired when a transaction is detected from an address on the platform blacklist. The payment cannot proceed.

json
{
  "event": "payment.blacklisted",
  "timestamp": "2026-05-16T12:03:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "BLACKLISTED"
  }
}

No sender address or reason is included for security reasons.

payment.failed ​

Fired when a system error occurs during payment processing that requires investigation.

json
{
  "event": "payment.failed",
  "timestamp": "2026-05-16T12:03:00Z",
  "data": {
    "payment_id": "9f1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d",
    "status": "FAILED",
    "error": "Sweep transaction failed after maximum retries."
  }
}

Withdrawal events ​

withdrawal.completed ​

Fired when a withdrawal transaction has been confirmed on-chain and the funds have arrived at your wallet.

json
{
  "event": "withdrawal.completed",
  "timestamp": "2026-05-16T14:00:00Z",
  "data": {
    "withdrawal_id": "w1x2y3z4-...",
    "amount_usdt": 147.75,
    "tx_hash": "0xwithdrawal...",
    "chain": "ethereum",
    "destination_address": "0xyourwallet...",
    "completed_at": "2026-05-16T14:00:00Z"
  }
}

withdrawal.failed ​

Fired when a withdrawal transaction fails and cannot be automatically retried.

json
{
  "event": "withdrawal.failed",
  "timestamp": "2026-05-16T14:00:00Z",
  "data": {
    "withdrawal_id": "w1x2y3z4-...",
    "amount_usdt": 147.75,
    "chain": "ethereum",
    "error": "Transaction broadcast failed: insufficient gas"
  }
}

Event subscription ​

You can subscribe to specific event types in the Client Portal → Dashboard → Webhooks, or via PUT /v1/webhooks:

json
{
  "events": [
    "payment.completed",
    "payment.expired_selection",
    "payment.reselected",
    "withdrawal.completed",
    "withdrawal.failed"
  ]
}

Use ["*"] to receive all events.

TokenCashFlow Documentation