Payment webhook events are delivered inside the standard envelope described on the General page. The data.object field contains a Payment resource.
Event Types
| Event | Fired when |
|---|---|
payment.quote_created | Exchange rate is locked and the quote is ready |
payment.steps_created | Route planning is complete and execution steps are created |
payment.balance_updated | Balance check result is available (reserved or awaiting funds) |
payment.risk_updated | Risk status has changed (e.g. auto_approved, awaiting_decision, or auto_rejected) |
For a detailed breakdown of what each event means in the context of a payout, see Payout Workflow.
Step Events
Once steps are created (payment.steps_created), individual step lifecycle events fire as each step progresses:
| Event | Fired when |
|---|---|
step.submitted | Step has been submitted for execution |
step.confirmed | Step execution is confirmed on-chain or by the partner |
step.finalized | Step has reached finality |
step.completed | Step finished successfully |
step.failed | Step encountered an error and could not complete |
The data.object for step events is a TransferStep resource.
Payload
The data.object in each event contains the full payment resource, including its steps. For the complete field reference, see the Payment schema.
For a walkthrough of how these events appear during a real payout lifecycle, see Create a Payout.
Key Status Fields
For details on how risk_status and balance_status evolve through a payout, see Payout Workflow.