代收下单与查询:字段、金额和订单状态
你的服务端先保存本地业务订单,再创建代收订单;网络超时或支付结果未知时,使用原商户订单号查询。两类调用都需要商户号、当前毫秒时间戳和服务端签名。
文章目录
下单接口: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 超时不是订单状态。记录“结果待确认”,用原商户订单号查单;结果确认前不要认定原请求必然失败,也不要通过重新编号绕过重复检查。
回调与查单使用同一支付处理函数
- 定位原订单按商户号和商户订单号读取本地记录,确认所属客户和环境。
- 核对可信结果回调先验签,查单使用受保护的后端请求,并按联调规范验证响应。
- 统一幂等更新成功状态只落库一次,交付任务使用唯一业务键。
- 记录不一致金额、币种或状态不符时停止交付,由技术人员协助核实。