Overview
Payout webhooks notify your system about payout status changes, payout confirmation, transaction hash receipt, and validation errors.
Use these webhooks to keep payout statuses synchronized in your system. After receiving a webhook, we recommend requesting the payout details through the API to verify the latest state.
Webhook events
| Event type | Trigger | Merchant action |
|---|
| PAYOUT_CHANGE_STATUS | Payout status changed to CREATION_IN_PROGRESS, PENDING_CONFIRMATION, IN_PROGRESS, CANCELED, FAILED, PARTIAL, or COMPLETED. | Update payout status in your system and request payout details if needed. |
| PAYOUT_CONFIRMED | Payout has been confirmed by all required process participants. | Continue tracking payout status. |
| PAYOUT_HASH_RECEIVED | Payout received a blockchain transaction hash but has not yet received all network confirmations. | Save the transaction hash and continue tracking final status. |
| PAYOUT_VALIDATION_ERROR | Validation error occurred during payout processing. | Check validation details and create a new payout with corrected data, if needed. |
Handling recommendations
| Recommendation | Description |
|---|
| Verify webhook data | After receiving a webhook, request payout details using [POST] payout or [POST] payout/mass. |
| Use idempotency | Webhook delivery can be repeated. Process webhooks idempotently by event type and payout identifier. |
| Track final statuses | Treat COMPLETED, FAILED, and CANCELED as final statuses. For mass payouts, PARTIAL means one or more payouts from the list were not completed successfully. |
| Store transaction hash | Use PAYOUT_HASH_RECEIVED to store the blockchain hash before the payout reaches a final status. |
Payloads
PAYOUT_CHANGE_STATUS
| Parameter | Type | Description |
|---|
| hash | string | Transaction hash, if available. |
| type | string | Event type: PAYOUT_CHANGE_STATUS. |
| parentExternalId | number | System ID of the payout. |
| createdDate | string | Date and time of payout creation. |
| payoutStatus | string | Current payout status. |
| idempotencyKey | string | External ID generated by the merchant while creating the payout through API. |
| currency | string | Payout currency. |
| externalId | string | External identifier passed by the merchant when creating the payout. |
PAYOUT_CONFIRMED
| Parameter | Type | Description |
|---|
| type | string | Event type: PAYOUT_CONFIRMED. |
| parentExternalId | number | System ID of the payout. |
| createdDate | string | Date and time of payout creation. |
| approved | array | List of users who approved the payout. |
| idempotencyKey | string | External ID generated by the merchant while creating the payout through API. |
| currency | string | Payout currency. |
| externalId | string | External identifier passed by the merchant when creating the payout. |
PAYOUT_HASH_RECEIVED
| Parameter | Type | Description |
|---|
| hash | string | Blockchain transaction hash. |
| type | string | Event type: PAYOUT_HASH_RECEIVED. |
| parentExternalId | number | System ID of the payout. |
| createdDate | string | Date and time of payout creation. |
| payoutStatus | string | Current payout status. |
| idempotencyKey | string | External ID generated by the merchant while creating the payout through API. |
| currency | string | Payout currency. |
| externalId | string | External identifier passed by the merchant when creating the payout. |
PAYOUT_VALIDATION_ERROR
| Parameter | Type | Description |
|---|
| type | string | Event type: PAYOUT_VALIDATION_ERROR. |
| parentExternalId | number | System ID of the payout. |
| message | string | Validation error message. |
| createdDate | string | Date and time of payout creation. |
| dealWithdrawalId | number | System ID of the withdrawal where the validation error occurred. |
| validationStatus | string | Validation error reason. |
| idempotencyKey | string | External ID generated by the merchant while creating the payout through API. |
| currency | string | Payout currency. |
| externalId | string | External identifier passed by the merchant when creating the payout. |