跳转到主要内容
启润支付会为以下事件类型发送 Webhook 通知。

​
事件类型

事件描述触发条件
order.paid付款已确认客户完成收银台付款
order.refunded订单退款已生效退款成功
order.closed订单未成功付款并已关闭付款取消、失败、超时、授权释放，或网关关闭订单

​
事件对象结构

所有 Webhook 事件共享相同的顶层结构： 
{
  "id": "evt_abc123",
  "type": "order.paid",
  "created_at": 1736932500000,
  "data": {
    // 事件特定数据
  }
}
字段类型描述
idstring唯一事件标识符（用于去重）
typestring事件类型
created_atintegerUnix 毫秒时间戳
dataobject事件特定载荷

​
order.paid

客户成功完成付款时发送。 
{
  "id": "evt_abc123",
  "type": "order.paid",
  "created_at": 1736932500000,
  "data": {
    "order_id": "order_def456",
    "product_id": "prod_abc123",
    "customer_email": "customer@example.com",
    "amount": "9.99",
    "currency": "USD",
    "net_amount": "9.29",
    "paid_at": 1736932500000,
    "metadata": { "user_id": "u_123" }
  }
}
字段类型描述
order_idstring订单 ID
product_idstring购买的产品
customer_emailstring客户邮箱地址
amountstring总支付金额
currencystring三字母货币代码
net_amountstring扣除手续费后的金额
paid_atinteger付款确认时间（Unix 毫秒时间戳）
metadataobject | null创建 Checkout Session 时传入的 metadata
这是最重要的事件。用它来完成订单处理 — 例如，为用户的账户充值额度。

​
order.refunded

订单退款已生效时发送。你可以用此事件更新权益、余额或对账记录。 有关控制台退款申请流程和退款状态定义，请查看订单退款。 
{
  "id": "evt_refund123",
  "type": "order.refunded",
  "created_at": 1736932600000,
  "data": {
    "order_id": "order_def456",
    "refund_id": "refund_abc123",
    "refund_status": "PARTIAL",
    "amount": "2.50",
    "currency": "USD",
    "refunded_amount": "2.50",
    "original_amount": "9.99",
    "reason": "customer_request",
    "metadata": { "user_id": "u_123" }
  }
}
字段类型描述
order_idstring订单 ID
refund_idstring退款 ID
refund_statusstring订单退款状态，例如 PARTIAL 或 FULL
amountstring本次事件对应的退款金额
currencystring三字母货币代码
refunded_amountstring本次退款后订单累计已退款金额
original_amountstring原订单金额
reasonstring | null退款原因
metadataobject | null创建 Checkout Session 时传入的 metadata

​
order.closed

订单未成功付款并关闭时发送。 
{
  "id": "evt_closed123",
  "type": "order.closed",
  "created_at": 1736932700000,
  "data": {
    "order_id": "order_def456",
    "product_id": "prod_abc123",
    "customer_email": "customer@example.com",
    "amount": "9.99",
    "currency": "USD",
    "closed_at": 1736932700000,
    "close_reason": "payment_timeout",
    "compat": { "epay_trade_status": "TRADE_CLOSED" },
    "metadata": { "user_id": "u_123" }
  }
}
字段类型描述
order_idstring订单 ID
product_idstring购买的产品
customer_emailstring客户邮箱地址
amountstring订单总金额
currencystring三字母货币代码
closed_atinteger订单关闭时间（Unix 毫秒时间戳）
close_reasonstring关闭原因，例如 payment_canceled、payment_failed、payment_timeout、authorization_released 或 gateway_closed
compatobject面向旧处理器的兼容字段
metadataobject | null创建 Checkout Session 时传入的 metadata

​
处理事件

以下是在 Webhook 端点中处理事件的方式： 
app.post('/webhooks/kyren', (req, res) => {
  // ... 先验证签名 ...

  const event = JSON.parse(req.body.toString());

  switch (event.type) {
    case 'order.paid':
      handleOrderPaid(event.data);
      break;
    case 'order.refunded':
      handleOrderRefunded(event.data);
      break;
    case 'order.closed':
      handleOrderClosed(event.data);
      break;
    default:
      console.log(`未处理的事件类型: ${event.type}`);
  }

  res.status(200).send('OK');
});