代收下單與查詢:字段、金額和訂單狀態
你的服務端先保存本地業務訂單,再創建代收訂單;網絡超時或支付結果未知時,使用原商戶訂單號查詢。兩類調用都需要商戶號、當前毫秒時間戳和服務端簽名。
文章目錄
下單接口:POST JSON
示例地址 https://gateway.example.com/api/pay/collect/create,方法 POST,請求頭 Content-Type: application/json,字符集 UTF-8。用實際開通的網關替換示例域名。
| 字段 | 必填 | 填寫規則 |
|---|---|---|
mchId | 是 | 你的商戶號;示例使用字符串。 |
wayCode | 是 | 已開通的通道或聚合編碼;示例使用字符串。 |
outTradeNo | 是 | 商戶訂單號,同一商戶內唯一,與本地訂單關聯。 |
amount | 是 | 下單金額,單位分;整數 1000 表示 10.00 元。 |
currencyCode | 否 | 幣種,默認 CNY。 |
notifyUrl | 是 | 你的異步通知地址,例如 https://merchant.example.com/pay/notify。 |
subject | 否 | 商品標題;提交時參與簽名。 |
body | 否 | 商品說明;提交時參與簽名。 |
clientIp | 否 | 客戶端 IP,按實際場景填寫。 |
reqTime | 是 | 當前毫秒時間戳,示例使用整數。 |
sign | 是 | 后端生成的小寫 MD5 簽名,不參與自身簽名。 |
金額由你的服務端從可信訂單記錄確定,不直接相信前端提交的價格。以整數分存儲下單金額,避免把 10.00 元填成 10 分,也避免未經處理的二進制浮點數進入金額計算。
創建訂單:字段示例
JSON 中所有身份和簽名都是占位值;reqTime 在實際請求中必須為當前毫秒整數,重新計算簽名后再提交。
{
"mchId": "MERCHANT_ID",
"wayCode": "80001",
"outTradeNo": "DEMO_COLLECT_001",
"amount": 1000,
"currencyCode": "CNY",
"notifyUrl": "https://merchant.example.com/pay/notify",
"subject": "DEMO_PRODUCT",
"reqTime": "CURRENT_UNIX_MILLISECONDS",
"sign": "RECOMPUTE_ON_YOUR_SERVER"
}import os
import time
from wenfupay_collect_sign import sign_collect
payload = {
"mchId": os.environ["MERCHANT_ID"],
"wayCode": "80001", # Use a code enabled for your merchant.
"outTradeNo": "YOUR_UNIQUE_ORDER_NO",
"amount": 1000, # 1000 cents = CNY 10.00.
"currencyCode": "CNY",
"notifyUrl": "https://merchant.example.com/pay/notify",
"reqTime": int(time.time() * 1000),
}
payload["sign"] = sign_collect(payload, os.environ["MD5_SECRET"])
# Send payload as JSON from your server to:
# API_BASE_URL + "/api/pay/collect/create"curl --request POST "$API_BASE_URL/api/pay/collect/create" \
--header "Content-Type: application/json; charset=UTF-8" \
--data @collect-create.json下載示例所用的 Python 簽名函數,計算規則見MD5簽名與驗簽。
查詢訂單:先簽名,再編碼查詢串
import os
import time
from urllib.parse import urlencode
from wenfupay_collect_sign import sign_collect
params = {
"mchId": os.environ["MERCHANT_ID"],
"outTradeNo": "YOUR_EXISTING_ORDER_NO",
"reqTime": int(time.time() * 1000),
}
# Alternative lookup: replace outTradeNo with platform_order_no.
params["sign"] = sign_collect(params, os.environ["MD5_SECRET"])
query_url = (
os.environ["API_BASE_URL"].rstrip("/")
+ "/api/pay/collect/query?" + urlencode(params)
)
# Send a server-side GET. Do not create another order on a timeout.支付寶、微信和通道編碼怎么選
80001 是支付寶聚合編碼,90001 是微信聚合編碼,也可使用分配的真實通道編碼。聚合只在已關聯、商戶已授權且啟用的候選真實通道中選擇,不代表所有商戶都自動可用。
服務端將產品里的支付選項映射到已開通的 wayCode。技術人員會確認可用編碼、通道限制和測試方式,前端無需了解內部路由配置。
僅當上游明確未受理時,聚合路由才可能嘗試下一候選。超時、異常或結果不確定時不會盲目切換;你的系統也應先查原訂單,避免生成多筆可能同時支付的訂單。
把下單響應接到你的支付頁面
JSON 響應頂層包含 code、message、data 和 sign。正常示例的 code 為 0;data 包含 duplicate、id、platformOrderNo、orderStatus、payUrl、channelErrorMessage。
保存平臺訂單號,用于查詢、通知匹配和對賬。只有取得真實有效的 payUrl 時才展示支付入口;它可能為空,不能自行拼接收銀臺網址。對鏈接協議和目標域名進行檢查,允許范圍在技術對接時配置。
code=0 不表示付款到賬,不能直接發卡或發貨。即使已經取得平臺訂單號,仍需等待可信的支付成功結果。完整錯誤碼處理和響應驗簽細節由技術人員在聯調時提供。
查單接口:GET 查詢原訂單
示例地址 https://gateway.example.com/api/pay/collect/query,方法 GET。先對實際查詢參數簽名,再使用標準 URL 編碼構造查詢串。
| 字段 | 必填 | 填寫規則 |
|---|---|---|
mchId | 是 | 訂單所屬商戶號。 |
outTradeNo | 二選一 | 商戶訂單號,與 platform_order_no 二選一。 |
platform_order_no | 二選一 | 平臺訂單號,注意使用下劃線命名。 |
reqTime | 是 | 本次查詢的當前毫秒時間戳。 |
sign | 是 | 按本次參數重新生成,不復用下單簽名。 |
查詢響應 data 示例包含 platformOrderNo、merchantOrderNo、amount、currencyCode、orderStatus、payUrl。請求的 platform_order_no 與響應的 platformOrderNo 拼寫不同,不要直接共用參數對象。
查詢響應 amount 的單位和精度,在開通時由技術人員確認。顯式轉換到你的內部金額口徑后再核對,不要直接拿它與下單的分金額比較。
訂單狀態與對應業務動作
| orderStatus | 含義 | 產品處理方式 |
|---|---|---|
0 | 待支付 | 展示等待付款,按計劃查詢,不能交付。 |
1 | 支付成功 | 核對可信結果后進入冪等交付流程。 |
2 | 支付失敗 | 記錄失敗;重新付款前按規則處理原訂單。 |
3 | 已關閉 | 結束等待,保留訂單與核對記錄。 |
4 | 已失效 | 展示失效,按約定處理重新購買與異常到賬。 |
HTTP 超時不是訂單狀態。記錄“結果待確認”,用原商戶訂單號查單;結果確認前不要認定原請求必然失敗,也不要通過重新編號繞過重復檢查。
回調與查單使用同一支付處理函數
- 定位原訂單按商戶號和商戶訂單號讀取本地記錄,確認所屬客戶和環境。
- 核對可信結果回調先驗簽,查單使用受保護的后端請求,并按聯調規范驗證響應。
- 統一冪等更新成功狀態只落庫一次,交付任務使用唯一業務鍵。
- 記錄不一致金額、幣種或狀態不符時停止交付,由技術人員協助核實。