GuidesAPI ReferenceChangelog
API Reference

Payouts

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

Eventdata.statusresource.typeresource.id
payout.transmittingTRANSMITTINGPAYOUTPayout ID (PO-...).
payout.sentSENTPAYOUTPayout ID.
payout.failedFAILEDPAYOUTPayout ID.
payout.returnedRETURNEDPAYOUTPayout ID.
conversion.completedCOMPLETEDCONVERSIONConversion UUID matching payout.conversion.id.
conversion.failedFAILEDCONVERSIONInternal 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

CodeDescription
INSUFFICIENT_FUNDSInsufficient funds.
PAYOUT_INITIATION_FAILEDFailed to initiate payout.
CONVERSION_INITIATION_FAILEDFailed to initiate conversion.
CONVERSION_FAILEDFailed to convert funds.
WITHDRAWAL_FAILEDFailed to withdraw funds.