Node.js 支付接入:在 Express 應用裏收款,從下單到 Webhook
用 Express 一步步完成 Node.js 支付接入:創建訂單、跳轉收銀台、驗證 Webhook 簽名、只履約一次,以及如何測試。
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.comAPI 密鑰只留在服務器上——永遠不要放進瀏覽器代碼。見 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" | …
}用它在成功頁上顯示正確的狀態,而不是用來履約,見 支付成功頁怎麼做。
第五步:在沙箱裏測試
- 啓動應用和隧道,然後通過
/checkout創建一張訂單。 - 在收銀台用測試卡
4242 4242 4242 4242付款,有效期填任意未來日期、安全碼任意——再用4000 0000 0000 0002試一次被拒。見 支付測試卡號大全。 - 看到
payment.succeeded到達後,故意返回一次500,確認重試被正確去重。 - 如果驗簽失敗,用控制台的發送測試回調和驗簽自檢排查。
上線只是換密鑰:把 kuko_test_ 密鑰和沙箱簽名密鑰換成同一個應用在正式環境的值,代碼其他部分都不用改。
總結
- Node.js 支付接入需要兩個 Express 路由:創建訂單並返回
checkout_url的POST /checkout,以及一個 Webhook 路由; - 在服務端創建訂單,用你的訂單 id 作為
out_trade_no,傳整數金額和Idempotency-Key; - 用
express.raw掛載 Webhook,對原始請求體驗證X-KukoPay-Signature,對測試回調只確認不處理; - 在同一個事務裏記錄事件 id 並履約;訂單查詢只用來顯示狀態;
- 用沙箱密鑰、測試卡和隧道測試,然後換成正式密鑰。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。