文档目录 · 查询代收

查询代收

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 时确认代收成功。

搜索文档