跳到主要内容

Payin Webhook

Payin Webhook 用于通知商户收款订单状态变化。当前商户对接主事件是：

acquiring.order.updated

商户创建 Payin 订单时需要传 notify_webhook_id，该 Webhook 必须启用并订阅 acquiring.order.updated、acquiring.payment.updated 或 acquiring.*。

触发时机​

acquiring.order.updated 会在订单进入需要商户处理的状态时推送，例如：

  1. 用户完成足额付款，订单变为 completed
  2. 用户只支付了部分金额，订单变为 partial_paid
  3. 订单过期且没有到账，订单变为 expired
  4. 订单过期时已有到账但不足额，订单变为 underpaid
  5. 订单过期后又检测到到账，anomaly_tag=expired_paid

Payload 示例​

{
  "event_id": "acqevt_acq_order_xxx",
  "event_type": "acquiring.order.updated",
  "business_type": "acquiring",
  "business_id": "acq_order_xxx",
  "occurred_at": 1781789497,
  "version": "v1",
  "data": {
    "provider_event": "transaction_confirmed",
    "anomaly_tag": "",
    "order_id": "acq_order_xxx",
    "platform_order_no": "P202606190001",
    "out_trade_no": "payin_202606190001",
    "previous_status": "pending",
    "status": "completed",
    "status_changed": true,
    "amount_changed": true,
    "order_currency": "USD",
    "pay_amount": "20.00",
    "paid_amount_total": "20.00",
    "remaining_amount": "0",
    "overpaid_amount": "0",
    "underpay_tolerance": "0",
    "expire_time": 1781789497,
    "updated_at": 1781789497
  }
}

核心字段​

字段说明
event_idWebhook 事件 ID，用于幂等
event_type固定为 acquiring.order.updated
business_id等于 order_id
data.order_idBeyounger 收款订单 ID
data.out_trade_no商户订单号
data.previous_status变更前状态
data.status最新订单状态
data.pay_amount应付金额
data.paid_amount_total已确认到账金额
data.remaining_amount剩余应付金额
data.overpaid_amount多付金额
data.underpay_tolerance少付容差
data.anomaly_tag异常标记

数币收单状态​

数币收单的状态由订单下的支付记录聚合而来。不要只按“成功/失败”理解。

data.status是否终态说明商户处理
partial_paid否已有部分金额确认到账，但确认金额不足不要标记成功，继续等待或提示补款
completed是已确认金额加少付容差后满足订单金额标记商户订单支付成功
underpaid是订单过期时已有到账，但金额不足且超过容差标记异常，进入补款、退款或人工处理
expired是订单过期且没有确认到账标记过期

补充说明：

  1. paid_amount_total 是已确认到账金额。
  2. 未确认的链上交易不应直接当作支付成功。
  3. overpaid_amount > 0 表示用户多付，需要按商户规则处理。
  4. anomaly_tag=expired_paid 表示过期后到账，不建议自动按正常成功处理。
  5. 一个订单可能有多笔 payment，订单业务结果以聚合后的 data.status 为准。

商户处理建议​

  1. 先验签，再处理业务。
  2. 按 event_id 做幂等。
  3. 按 data.order_id 或 data.out_trade_no 找到商户订单。
  4. 只有 data.status=completed 才标记支付成功。
  5. 对 partial_paid、underpaid、expired_paid 建立异常处理流程。
  6. 收到 Webhook 后可调用 GET /payment/acquiring/orders/{order_id} 补偿确认。