查询代收
POST /api/v1/pay/query
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
platform_order_no |
string | 条件 | 平台订单号;两个订单号至少提供一个 |
merchant_order_no |
string | 条件 | 商户订单号;同时提供时须指向同一会话或订单 |
请求示例:
{
"api_key": "<API_KEY>",
"merchant_id": "merchant_1001",
"merchant_order_no": "PAY202609160001",
"timestamp": "1789516800",
"nonce": "query-550e8400-e29b-41d4-a716-446655440000",
"sign": "<64位小写HMAC-SHA256>"
}
会话响应示例:
{
"code": 0,
"message": "OK",
"data": {
"checkout_mode": "cashier",
"platform_order_no": "P202609160001",
"merchant_order_no": "PAY202609160001",
"amount": "100.00",
"currency": "MYR",
"status": "awaiting_payment_method",
"expired_at": "2026-09-16T15:30:00Z"
},
"request_id": "req_01JEXAMPLE"
}
正式订单返回订单号、金额、币种和 status,以及已确定的 channel_code、fee_amount、net_amount;fee_amount 使用订单创建时锁定的商户费率快照,net_amount = amount - fee_amount。例如 amount=10.00、fee_amount=0.15 时,net_amount=9.85。上游订单号 channel_order_no 及 expired_at 按订单实际情况返回。成功时包含 paid_amount 和 paid_at。
| 正式订单状态 | 说明 | 终态 |
|---|---|---|
created |
已创建 | 否 |
pending |
等待支付结果 | 否 |
paid |
支付成功 | 是 |
failed |
支付失败 | 是 |
expired |
已过期 | 是 |
closed |
已关闭 | 是 |
manual_review |
待人工确认,请等待最终结果 | 否 |
Provider 明确拒绝创建代收时,正式订单会成为 failed,并按 payin.failed 通知商户。若提交超时、断线或响应无法确认,订单可能继续为 pending;请使用原订单号查询,不要据此重复创建。Cashier 提交失败时可能返回 50009 / error.cashier_provider_message,但同一会话已保存失败结果,重复操作不会再次请求 Provider。历史 pending 订单不会因该规则自动改写。
通道处于 maintenance 时仍可查询已有订单的本地状态;维护不是订单失败依据。仅查询或验签成功的通知显示 paid 时确认代收成功。