Webhooks
Events
Reference for every webhook event type: when it fires, what it means, and example payloads.
Event catalog
Subscribe only to the types you need when creating an endpoint. All events share the same envelope (id, type, api_version, data).
Payment intents
payment_intent.created— intent created; deposit address available. Includes funding policy echo and optional fee preview.payment_intent.deposit_confirmed— on-chain deposit reached confirmations and passed funding gates. Customer has paid; funds are not yet in your balance.payment_intent.completed— settlement finished; funds credited or delivered per your settlement destination. Use for fulfillment.payment_intent.credited— deprecated; usepayment_intent.completed.
Payouts
payout.createdpayout.processingpayout.completedpayout.failed
deposit_confirmed vs completed
deposit_confirmed means the customer sent enough confirmed on-chain funds. completed means your merchant balance was updated or settlement finished. Show “payment received” on the former; start fulfillment on the latter.Payment intent field semantics
These fields appear on deposit_confirmed and completed payloads under data.payment_intent:
requested_chain/requested_token— what the intent asked for at creation.chain/token— the on-chain funded asset (may differ after a cross-asset deposit).settled_chain/settled_token/settled_amount— what was credited to your merchant balance (completedonly).*_base_unitsandsettled_amountare integer strings;*_decimalfields are display helpers.metadata— your merchant-defined key/value pairs from intent creation.
payment_intent.deposit_confirmed
{
"id": "evt_def456",
"type": "payment_intent.deposit_confirmed",
"api_version": "2026-05-10",
"created_at": "2026-04-01T12:05:00.000Z",
"merchant_id": "merchant_xyz",
"environment": "test",
"data": {
"payment_intent": {
"payment_intent_id": "pi_01JXYZ",
"requested_chain": "ethereum",
"requested_token": "usdc",
"chain": "ethereum",
"token": "usdc",
"raw_deposit_amount": "10500000",
"amount": "10.50",
"amount_base_units": "10500000",
"decimals": 6,
"confirmations": 12,
"required_confirmations": 12,
"tx_hash": "0xabc123...",
"confirmed_at": "2026-04-01T12:05:00.000Z",
"metadata": { "order_id": "ORD-001" }
}
}
}payment_intent.completed
{
"id": "evt_ghi789",
"type": "payment_intent.completed",
"api_version": "2026-05-10",
"created_at": "2026-04-01T12:10:00.000Z",
"merchant_id": "merchant_xyz",
"environment": "test",
"data": {
"payment_intent": {
"payment_intent_id": "pi_01JXYZ",
"requested_chain": "ethereum",
"requested_token": "usdc",
"chain": "ethereum",
"token": "usdc",
"credited_at": "2026-04-01T12:10:00.000Z",
"metadata": { "order_id": "ORD-001" },
"settled_chain": "ethereum",
"settled_token": "usdc",
"settled_amount": "10450000",
"settled_amount_decimal": "10.45",
"raw_deposit_amount": "10500000",
"amount": "10.50",
"amount_base_units": "10500000",
"decimals": 6,
"raw_deposit_amount_decimal": "10.50",
"fees": {
"asset": "usdc:ethereum",
"amount_base_units": "50000",
"amount": "0.05"
},
"settlement": {
"destination": "MERCHANT_CUSTODY",
"plan_status": "COMPLETED",
"execution_kind": "DIRECT_CREDIT",
"execution_status": "COMPLETED",
"tx_hash": null,
"payout_request_id": null
}
}
}
}payout.completed
{
"id": "evt_payout01",
"type": "payout.completed",
"api_version": "2026-05-10",
"created_at": "2026-04-01T14:00:00.000Z",
"merchant_id": "merchant_xyz",
"environment": "test",
"data": {
"payout": {
"payout_request_id": "po_01JXYZ",
"asset": "usdc:ethereum",
"token": "usdc",
"chain": "ethereum",
"amount": "1000000",
"amount_base_units": "1000000",
"status": "COMPLETED",
"completed_at": "2026-04-01T14:00:00.000Z"
}
}
}payout.failed uses the same shape with status: "FAILED", failed_at, failure_code, and failure_message. Lifecycle events payout.created and payout.processing include asset, token, chain, and amount_base_units.