Notifications for Payouts payments and their conversions.
Use Get Payout to retrieve the current amounts, fees and payment details after a notification. See Webhooks for delivery, retries and deduplication, and Webhook Authentication for signature verification. Deliveries can arrive late, more than once or out of order.
Events
| Event | data.status | resource.type | resource.id |
|---|---|---|---|
payout.transmitting | TRANSMITTING | PAYOUT | Payout ID (PO-...). |
payout.sent | SENT | PAYOUT | Payout ID. |
payout.failed | FAILED | PAYOUT | Payout ID. |
payout.returned | RETURNED | PAYOUT | Payout ID. |
conversion.completed | COMPLETED | CONVERSION | Conversion UUID matching payout.conversion.id. |
conversion.failed | FAILED | CONVERSION | Internal conversion UUID matching payout.conversion.id. |
Payout events
data.from_account identifies the account funding the payout, including when on_behalf_of_account is used. Failed events also include data.status_info, an object containing code and description, or null when no reason is available. A failed payout does not undo a conversion that has already completed.
{
"event_name": "payout.sent",
"resource": {
"type": "PAYOUT",
"id": "PO-7Q2K-M9XD"
},
"data": {
"from_account": "BZ-7Q2K-M9XD",
"status": "SENT"
}
}Conversion events
For an internal conversion, conversion.completed reports completion before the subsequent withdrawal finishes. conversion.failed identifies the failed conversion by UUID, followed by payout.failed identifying the payout by PO-....
For an external conversion, conversion and withdrawal complete together. conversion.completed is emitted before payout.sent, using the withdrawal UUID as the conversion ID. Delivery order is not guaranteed. Retrieve the payout with its payout ID, not the conversion UUID.
{
"event_name": "conversion.failed",
"resource": {
"type": "CONVERSION",
"id": "550e8400-e29b-41d4-a716-446655440002"
},
"data": {
"from_account": "BZ-7Q2K-M9XD",
"status": "FAILED",
"status_info": {
"code": "CONVERSION_FAILED",
"description": "Failed to convert funds."
}
}
}Status information
| Code | Description |
|---|---|
INSUFFICIENT_FUNDS | Insufficient funds. |
PAYOUT_INITIATION_FAILED | Failed to initiate payout. |
CONVERSION_INITIATION_FAILED | Failed to initiate conversion. |
CONVERSION_FAILED | Failed to convert funds. |
WITHDRAWAL_FAILED | Failed to withdraw funds. |
