跳轉到主要內容

Node.js 支付接入:在 Express 應用裏收款,從下單到 Webhook

用 Express 一步步完成 Node.js 支付接入:創建訂單、跳轉收銀台、驗證 Webhook 簽名、只履約一次,以及如何測試。

發佈於 約 3 分鐘閲讀

手繪插畫:一個 Express 服務器有 POST /checkout 和 POST /webhooks 兩個路由,連到託管收銀台再返回,旁邊一個人雙手插兜
本文目錄
  1. 準備工作
  2. 第一步:創建訂單並跳轉收銀台
  3. 第二步:接收並驗證 Webhook
  4. 第三步:只履約一次
  5. 第四步:兜底的訂單查詢
  6. 第五步:在沙箱裏測試
  7. 總結

Node.js 支付接入,在你的服務器上只需要兩個路由:一個創建訂單並把買家送到收銀台,另一個接收告訴你支付成功的 Webhook。中間的一切——卡表單、錢包、3D Secure、被拒後重試——都在託管收銀台上完成,所以你的 Express 應用從不接觸銀行卡信息。

這篇教程用 Express 和 KukoPay 一步步搭建這套接入:準備工作、創建訂單、帶驗簽的 Webhook 路由、只履約一次、兜底的訂單查詢,以及在沙箱裏把這一切測試一遍。

準備工作

  • Node.js 18 或更高版本(自帶 fetch)和 Express。
  • 在 開發者 → API 密鑰 取得的沙箱 API 密鑰(kuko_test_…)——沙箱不需要資質審核。見 沙箱與正式環境的區別。
  • 一個用於 Webhook 的公網 HTTPS 地址。在筆記本上可以用隧道,見 如何在本地測試 Webhook。
npm install express
export KUKOPAY_API_KEY=kuko_test_...
export KUKOPAY_WEBHOOK_SECRET=...   # 應用的回調簽名密鑰
export PUBLIC_URL=https://your-tunnel.example.com

API 密鑰只留在服務器上——永遠不要放進瀏覽器代碼。見 API 密鑰能放在前端嗎。

第一步:創建訂單並跳轉收銀台

import express from "express"
import crypto from "crypto"
 
const app = express()
const API = "https://api.kukopay.com/v1"
 
app.post("/checkout", express.json(), async (req, res) => {
  const order = await db.orders.create({ product: req.body.product, amount: 2990 }) // 你自己的訂單
  const r = await fetch(`${API}/orders`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": process.env.KUKOPAY_API_KEY,
      "Idempotency-Key": `create-${order.id}`,
    },
    body: JSON.stringify({
      out_trade_no: order.id,
      amount: order.amount,           // 以分為單位的整數:2990 = $29.90
      currency: "USD",
      subject: "Pro 套餐 1 年",
      notify_url: `${process.env.PUBLIC_URL}/webhooks/kukopay`,
      return_url: `${process.env.PUBLIC_URL}/orders/{OUT_TRADE_NO}/complete`,
    }),
  })
  const body = await r.json()
  if (!r.ok) {
    console.error("create order failed", body.request_id, body.error)
    return res.status(502).json({ error: "checkout_unavailable" })
  }
  await db.orders.update(order.id, { trade_no: body.data.trade_no })
  res.json({ checkout_url: body.data.checkout_url })
})

要點:

  • 你的訂單 id 就是 out_trade_no,重試時返回的是同一張訂單,而不是第二張,見 冪等鍵是什麼。
  • 金額來自你的服務器,是以分為單位的整數,見 支付接口為什麼用「分」傳金額。
  • notify_url 把這張訂單的 Webhook 發到你的路由,用應用的回調簽名密鑰簽名。
  • 失敗時記錄 request_id,用它能在 API 日誌裏找到這次調用,見 支付接口錯誤處理。

之後瀏覽器把 window.location 設為 checkout_url 即可。

第二步:接收並驗證 Webhook

用 express.raw 掛載 Webhook 路由,這樣驗簽用的就是被簽名的原始字節:

function verify(rawBody, header, secret) {
  const parts = header.split(",").map((p) => [p.slice(0, p.indexOf("=")).trim(), p.slice(p.indexOf("=") + 1).trim()])
  const t = parts.find(([k]) => k === "t")?.[1]
  const sigs = parts.filter(([k]) => k === "v1").map(([, v]) => v)
  if (!t || !sigs.length || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false
  const expected = Buffer.from(crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex"))
  return sigs.some((s) => { const b = Buffer.from(s); return b.length === expected.length && crypto.timingSafeEqual(b, expected) })
}
 
app.post("/webhooks/kukopay", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8")
  if (!verify(raw, req.get("X-KukoPay-Signature") || "", process.env.KUKOPAY_WEBHOOK_SECRET)) {
    return res.status(400).end()
  }
  const event = JSON.parse(raw)
  if (event.test) return res.status(200).end()       // 測試回調:確認收到,永不履約
 
  await handleEvent(event)
  res.status(200).end()
})

任意一個 v1 匹配即可接受:密鑰輪換期間請求頭裏會有兩個。見 Webhook 驗簽怎麼做。

第三步:只履約一次

async function handleEvent(event) {
  await db.transaction(async (tx) => {
    const fresh = await tx.events.insertIfAbsent(event.id)   // 事件 id 上有唯一約束
    if (!fresh) return                                        // 已經處理過
    if (event.type === "payment.succeeded") {
      const o = event.data.object
      await tx.orders.markPaid(o.out_trade_no, { trade_no: o.trade_no, amount: o.amount })
      await tx.jobs.enqueue("fulfil", { orderId: o.out_trade_no })
    }
  })
}

在同一個事務裏記錄事件 id 和狀態變更,重試的 Webhook 就不會履約兩次;把耗時的工作(郵件、開通)交給隊列,讓路由在 10 秒內返回。見 支付回調冪等處理。

第四步:兜底的訂單查詢

當買家比 Webhook 先到達成功頁,或者漏收了 Webhook 時,直接問 KukoPay:

async function orderStatus(outTradeNo) {
  const r = await fetch(`${API}/orders/${encodeURIComponent(outTradeNo)}`, {
    headers: { "X-Api-Key": process.env.KUKOPAY_API_KEY },
  })
  return (await r.json()).data.status   // "pending" | "paid" | "expired" | "failed" | …
}

用它在成功頁上顯示正確的狀態,而不是用來履約,見 支付成功頁怎麼做。

第五步:在沙箱裏測試

  1. 啓動應用和隧道,然後通過 /checkout 創建一張訂單。
  2. 在收銀台用測試卡 4242 4242 4242 4242 付款,有效期填任意未來日期、安全碼任意——再用 4000 0000 0000 0002 試一次被拒。見 支付測試卡號大全。
  3. 看到 payment.succeeded 到達後,故意返回一次 500,確認重試被正確去重。
  4. 如果驗簽失敗,用控制台的發送測試回調和驗簽自檢排查。

上線只是換密鑰:把 kuko_test_ 密鑰和沙箱簽名密鑰換成同一個應用在正式環境的值,代碼其他部分都不用改。

總結

  • Node.js 支付接入需要兩個 Express 路由:創建訂單並返回 checkout_url 的 POST /checkout,以及一個 Webhook 路由;
  • 在服務端創建訂單,用你的訂單 id 作為 out_trade_no,傳整數金額和 Idempotency-Key;
  • 用 express.raw 掛載 Webhook,對原始請求體驗證 X-KukoPay-Signature,對測試回調只確認不處理;
  • 在同一個事務裏記錄事件 id 並履約;訂單查詢只用來顯示狀態;
  • 用沙箱密鑰、測試卡和隧道測試,然後換成正式密鑰。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。