跳轉到主要內容
啟潤支付會為以下事件類型發送 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');
});