Payout Webhook

Payout Webhook 用于通知商户出金验证、审核和执行状态。

Payout Webhook 分为三类：

1. 验证请求：payout.verify.request
2. 审核状态：payout.review.*
3. 执行状态：payout.execution.*

事件列表

事件	说明	是否终态
payout.verify.request	请求商户验证出金信息	否
payout.review.approved	验证或审核通过	否
payout.review.returned	出金被退回	通常需要人工处理
payout.review.rejected	出金被拒绝	是，未执行打款
payout.execution.processing	出金执行中	否
payout.execution.completed	出金执行成功	是
payout.execution.failed	出金执行失败	是

payout.verify.request

该事件发生在打款执行前，用于请求商户确认这笔出金是否允许继续。

商户应校验：

1. payout_id
2. reference
3. amount
4. currency
5. beneficiary_id
6. beneficiary_account_id
7. 收款账户信息和商户订单是否匹配

通过响应：

{
  "verified": true
}

拒绝响应：

{
  "verified": false
}

注意：payout.verify.request 不是成功通知。它只是执行打款前的验证请求。

执行结果 Payload 示例

{
  "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": ""
  }
}

核心字段

字段	说明
event_id	Webhook 事件 ID，用于幂等
event_type	事件类型
business_id	等于 payout_id
data.payout_id	Beyounger 出金 ID
data.reference	商户业务单号
data.amount / data.currency	出金金额和币种
data.status	出金总状态
data.review_status	验证或审核状态
data.execution_status	执行状态
data.execution_fail_reason	执行失败原因

状态判断

场景	判断方式	商户处理
验证通过	review_status=approved 或 payout.review.approved	等待执行结果，不要标记成功
验证拒绝	review_status=rejected 或 payout.review.rejected	标记出金拒绝，资金未执行
执行中	execution_status=processing	标记处理中
执行成功	execution_status=completed 或 payout.execution.completed	标记出金成功
执行失败	execution_status=failed 或 payout.execution.failed	标记出金失败，读取失败原因

最终成功只能以 execution_status=completed 为准，不能以审核通过为准。

商户处理建议

1. 先验签，再处理业务。
2. 按 event_id 做幂等。
3. 按 data.payout_id 或 data.reference 找到商户出金订单。
4. payout.review.approved 只代表可以执行，不代表打款成功。
5. payout.execution.completed 才代表最终成功。
6. 收到终态事件后可调用 GET /payment/payouts/{payout_id} 补偿确认。