Skip to main content
Every money-moving resource is created quickly and then moves — through providers, chains, and approvals. Your integration should react to states, not to HTTP responses.

​
Payouts

  • pending → processing → completed fires payout.completed; any → failed fires payout.failed with statusMessage.
  • A failed payout refunds the balance automatically — no refund call needed.
  • Retries against providers are internal; you’ll see them as attempts on GET /v1/payouts/{id} and in the timeline.

​
Collections (mobile money charges)

collection.pending on creation, then collection.completed (balance credited) or collection.failed. The “customer never approved” case is a normal failed.

​
Deposits (virtual accounts & crypto addresses)

Deposits aren’t requested — they arrive. Each one becomes a collection of type deposit and credits your balance; you get account.credited and the collection webhooks. Crypto deposits wait for chain confirmations first (the checkout shows this as “confirming”).

​
Orders (cross-rail pass-through)

Two extra states describe how much arrived: overpaid and underpaid. Both proceed — the order is recomputed on the actual amount received and pays out that amount; it fails only if the received amount is below the destination method’s minimum. Every transition fires an order.* webhook of the same name (order.funds_received, order.underpaid, …).

​
Conversions

Quote → execute. A quote is valid for 10 minutes; executing it moves money between two of your balances synchronously and returns completed. Executing the same quote twice returns the original conversion. A payment link is active until its sessions collect the full amount (paid), it passes its own expiresAt (expired), or you close it (closed). A failed or expired session never changes the link — the payer just picks another method. Partial payments accumulate on the link (totalReceived / remaining).

​
Reading state safely

  • Poll GET …/{id} for a one-off; use webhooks for everything else.
  • Webhooks can arrive out of order or twice. Treat the payload’s status as authoritative for that resource and make handlers idempotent on the resource id + status.
  • timeline on payout and order detail is the audit trail — it’s what the dashboard shows, assembled from the same records.