代收接口

代收下單與查詢:字段、金額和訂單狀態

你的服務端先保存本地業務訂單,再創建代收訂單;網絡超時或支付結果未知時,使用原商戶訂單號查詢。兩類調用都需要商戶號、當前毫秒時間戳和服務端簽名。

文章目錄

下單接口: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 在實際請求中必須為當前毫秒整數,重新計算簽名后再提交。

JSON 字段示例
{
  "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"
}
Python 后端組裝
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 傳輸方式
curl --request POST "$API_BASE_URL/api/pay/collect/create" \
  --header "Content-Type: application/json; charset=UTF-8" \
  --data @collect-create.json

下載示例所用的 Python 簽名函數,計算規則見MD5簽名與驗簽。

查詢訂單:先簽名,再編碼查詢串

Python GET 參數
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 超時不是訂單狀態。記錄“結果待確認”,用原商戶訂單號查單;結果確認前不要認定原請求必然失敗,也不要通過重新編號繞過重復檢查。

回調與查單使用同一支付處理函數

  1. 定位原訂單按商戶號和商戶訂單號讀取本地記錄,確認所屬客戶和環境。
  2. 核對可信結果回調先驗簽,查單使用受保護的后端請求,并按聯調規范驗證響應。
  3. 統一冪等更新成功狀態只落庫一次,交付任務使用唯一業務鍵。
  4. 記錄不一致金額、幣種或狀態不符時停止交付,由技術人員協助核實。

繼續閱讀簽名規則和回調處理細節。本文依據稳付pay接入規范整理。

按你的業務場景確認接入

說明商品、訂單量、支付方式與結算需求,逐項確認接口、資金路徑和異常處理。

聯系稳付pay ↗