跳轉到主要內容

交易號和訂單號的區別:該存哪個支付標識,按哪個對賬

交易號(支付 ID)和訂單號的區別:每個支付標識代表什麼、該保存哪個、按哪個對賬,以及聯繫客服時該提供哪個。

發佈於 約 3 分鐘閲讀

手繪插畫:一張標有 out_trade_no 和 trade_no 的訂單卡片,連着兩張 payment_id 卡片,其中一張被打叉,旁邊一個雙臂交叉的人
本文目錄
  1. 交易號和訂單號一覽
  2. 訂單號:out_trade_no 和 trade_no
  3. 支付 ID 是一筆交易,而且會變
  4. 退款單號和拒付單號
  5. 事件 ID 和請求 ID
  6. 什麼場景用哪個支付標識
  7. 總結

訂單號標識的是買了什麼;交易號(支付 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_numberKukoPay已支付訂單的收據生成後不變

訂單號: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。

在沙箱裏把它跑通

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