代收接口

代收下单与查询:字段、金额和订单状态

你的服务端先保存本地业务订单,再创建代收订单;网络超时或支付结果未知时,使用原商户订单号查询。两类调用都需要商户号、当前毫秒时间戳和服务端签名。

文章目录

下单接口: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 ↗