交易號和訂單號的區別:該存哪個支付標識,按哪個對賬
交易號(支付 ID)和訂單號的區別:每個支付標識代表什麼、該保存哪個、按哪個對賬,以及聯繫客服時該提供哪個。
訂單號標識的是買了什麼;交易號(支付 ID)標識的是為它付款的一次嘗試。一張訂單可以有多筆交易——一次被拒的銀行卡,然後一次錢包,再然後一次成功的銀行卡支付——而一筆交易只屬於一張訂單。把兩者搞混,是對賬 bug 最常見的來源之一:代碼按一個在結賬中途已經變了的交易號去匹配付款。
這篇文章解釋 KukoPay 接入中會遇到的每一種標識——訂單號、支付 ID、退款單號、事件和請求 ID——哪些要保存、按哪個匹配、聯繫客服時提供哪個。
交易號和訂單號一覽
| 標識 | 由誰生成 | 標識什麼 | 是否穩定 |
|---|---|---|---|
out_trade_no | 你 | 你的訂單——你系統裏的那次購買 | 是 |
trade_no(TRD_…) | KukoPay | 同一張訂單在 KukoPay 的編號 | 是 |
payment_id | 支付渠道 | 這張訂單的一次支付嘗試 | 否——結賬過程中可能變化 |
out_refund_no / refund_no | 你 / KukoPay | 一筆退款 | 是 |
dispute_no(dsp_…) | KukoPay | 一筆拒付 | 是 |
id(evt_…) | KukoPay | 一個事件(及其 Webhook) | 是 |
request_id(req_…) | KukoPay | 一次 API 調用 | 是 |
receipt_number | KukoPay | 已支付訂單的收據 | 生成後不變 |
訂單號:out_trade_no 和 trade_no
out_trade_no 是你自己的訂單號——由你決定,在同一個應用、同一個環境內唯一。它同時也是冪等鍵:用相同的 out_trade_no 和相同的內容再次下單,會返回原訂單而不是創建第二張,見 冪等鍵是什麼。
trade_no 是 KukoPay 給同一張訂單的編號,在創建訂單時返回。沙箱訂單以 TRD_SB_ 開頭。
訂單查詢接口兩者都接受:
curl "https://api.kukopay.com/v1/orders/ORD_20261118_0001" \
-H "X-Api-Key: $KUKOPAY_API_KEY"所以你很少需要兩個都存——但在訂單旁邊存一個 trade_no 幾乎沒有成本,還能讓和客服的溝通更快。
支付 ID 是一筆交易,而且會變
payment_id 標識的是當前掛在訂單上的那筆渠道支付。買家在收銀台更換支付方式時它會變化——平台先取消尚未完成的那筆支付,再創建新的一筆——所以一張訂單在支付成功前可能先後經過多個支付 ID。見 支付狀態詳解。
規則是:永遠不要用 payment_id 作為訂單的唯一標識。 用 trade_no / out_trade_no 和 payment.succeeded 事件把付款對應到訂單。訂單已支付或已關閉後仍然到達的付款會被自動退回,見 重複扣款怎麼辦。
退款單號和拒付單號
out_refund_no是你的退款單號,也是退款的冪等鍵——用同一個單號重試退款請求,會返回原退款而不會退兩次。正式環境退款必須傳入。refund_no是 KukoPay 的;退款查詢兩者都接受。dispute_no標識一筆拒付;拒付由買家的發卡行發起,所以沒有商戶側的單號。
事件 ID 和請求 ID
- 事件
id(evt_…)在同一條 Webhook 的每次重試中都相同。把它寫入帶唯一約束的表,每個事件就只會處理一次,見 支付回調冪等處理。 request_id(req_…)標識一次 API 調用,出現在每個響應體和X-Request-Id響應頭裏。請記入日誌:客服要的就是它,用它也能在 API 日誌裏找到這次調用,見 支付接口錯誤處理。
什麼場景用哪個支付標識
| 要做的事 | 用 |
|---|---|
| 把付款關聯到你的訂單 | out_trade_no(或 trade_no) |
| 查詢訂單 | 在 GET /v1/orders/{…} 裏用 out_trade_no 或 trade_no |
| 安全地重試下單 | 相同的 out_trade_no |
| 安全地重試退款 | 相同的 out_refund_no |
| Webhook 去重 | 事件 id |
| 對賬 | 資金流水,每一行都關聯到對應的訂單、退款、拒付或提現,見 支付對賬 |
| 就某次 API 調用詢問客服 | request_id |
| 幫買家找到一筆扣款 | 收據上的 receipt_number 或 out_trade_no |
總結
- 訂單號標識那次購買;交易號(支付 ID)標識一次付款嘗試,一張訂單可以有多筆;
- 在 KukoPay,
out_trade_no是你的,trade_no是 KukoPay 的——兩者都穩定,訂單查詢都接受; payment_id在結賬過程中可能變化,不要用它作為訂單標識;out_refund_no讓退款可以安全重試,事件id讓 Webhook 可以去重,request_id是客服需要的;- 在你的訂單上保存
out_trade_no和trade_no,並記錄每一個request_id。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。