Payout Webhooks

Payout webhooks notify merchants about payout verification, review, and execution states.

There are three groups:

1. Verification request: payout.verify.request
2. Review status: payout.review.*
3. Execution status: payout.execution.*

Events

Event	Meaning	Final?
payout.verify.request	Ask the merchant to verify payout information.	No
payout.review.approved	Verification or review approved.	No
payout.review.returned	Payout was returned.	Usually requires manual handling
payout.review.rejected	Payout was rejected.	Yes, payout was not executed
payout.execution.processing	Payout execution is in progress.	No
payout.execution.completed	Payout execution succeeded.	Yes
payout.execution.failed	Payout execution failed.	Yes

payout.verify.request

This event is sent before execution. It asks the merchant whether the payout is allowed to continue.

The merchant should validate:

1. payout_id
2. reference
3. amount
4. currency
5. beneficiary_id
6. beneficiary_account_id
7. Whether recipient account information matches the merchant order

Approve:

{
  "verified": true
}

Reject:

{
  "verified": false
}

payout.verify.request is not a success notification. It is only a pre-execution verification request.

Execution Payload Example

{
  "event_id": "payout_payout_xxx_abcd",
  "event_type": "payout.execution.completed",
  "business_type": "payout",
  "business_id": "payout_xxx",
  "occurred_at": 1781789497,
  "version": "v1",
  "data": {
    "payout_id": "payout_xxx",
    "reference": "po_202606190001",
    "currency": "USD",
    "amount": "0.5",
    "status": "completed",
    "review_status": "approved",
    "execution_status": "completed",
    "execution_fail_reason": ""
  }
}

Important Fields

Field	Description
event_id	Webhook event ID for idempotency.
event_type	Event type.
business_id	Same as payout_id.
data.payout_id	Beyounger payout ID.
data.reference	Merchant payout reference.
data.amount / data.currency	Payout amount and currency.
data.status	Top-level payout status.
data.review_status	Verification or review status.
data.execution_status	Execution status.
data.execution_fail_reason	Execution failure reason.

State Guide

Scenario	How to identify	Merchant action
Review approved	review_status=approved or payout.review.approved	Wait for execution result. Do not mark as paid.
Review rejected	review_status=rejected or payout.review.rejected	Mark payout rejected. Funds were not executed.
Processing	execution_status=processing	Mark as processing.
Execution succeeded	execution_status=completed or payout.execution.completed	Mark payout successful.
Execution failed	execution_status=failed or payout.execution.failed	Mark payout failed and inspect failure reason.

Final success must be based on execution_status=completed, not review approval.

Merchant Handling

1. Verify the signature before business processing.
2. Use event_id for idempotency.
3. Find the merchant payout by data.payout_id or data.reference.
4. payout.review.approved means execution may start; it does not mean success.
5. payout.execution.completed is final success.
6. Query GET /payment/payouts/{payout_id} for fallback confirmation.