PAYOUT_SUCCESSFUL
Delivered when a payout reaches COMPLETED — the transfer is confirmed
on-chain. Use it to reconcile your ledger, release downstream workflows, or
notify your customer.
Delivered to your business webhook URL.
This event fires only for completed payouts. There is no webhook for
PENDING, PROCESSING, or FAILED — to detect a failure, read the payout
back with
Retrieve a payout or
Get payout status.
Payload
{
"body": {
"eventType": "PAYOUT_SUCCESSFUL",
"payout": {
"id": "8e5697e3-8265-455b-984a-0eb40e10b0f9",
"businessId": "b7b93a40-4e18-4e97-9c5f-8a7a4fd0df92",
"network": "MATIC_MAINNET",
"token": "USDT",
"amount": "100.250000000000000000",
"toAddress": "0x56adfcc254ab3b8142a275c1837bcffaff5aa38b",
"merchantReference": "INV-2045",
"transactionHash": "0xb0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f70819",
"status": "COMPLETED",
"info": null,
"createdAt": "2024-10-02T11:21:33.000000Z",
"updatedAt": "2024-10-02T11:32:01.000000Z"
}
}
}Unlike the collection events, this payload uses camelCase keys. Do not share a parser between the two without normalising first.
Handling
Verify and acknowledge
Check X-Signature against the raw body, then return 2xx straight away. See
Webhooks for the verification snippet.
Deduplicate on merchantReference
merchantReference is the value you supplied when creating the payout, so it
maps directly to your own ledger entry. Check whether you have already marked
it complete before doing anything else — this event can arrive more than once.
Settle
Mark the payout complete, release any funds you were holding, and record
transactionHash for your audit trail.
Not receiving it?
- Confirm the webhook URL and secret in Business → Developer → Webhooks, and that the endpoint is publicly reachable.
- Check the delivery attempts in the dashboard — a
4xxfrom your endpoint is recorded there along with the response body. - Confirm the payout actually reached
COMPLETED; a payout stuck inPROCESSINGproduces no event. - Remember the retry window is roughly 36 minutes. Past that, reconcile with List payouts.
See also
- Create a payout
- Webhooks overview — signature verification and retries
