代收(收款)

商户下单后,用户访问平台返回的 pay_url 完成支付;订单到达终态时平台回调通知。

下单 POST /pay/create

请求业务参数(另带 公共参数):

字段	必填	说明
mch_order_no	是	商户订单号,商户内唯一
product_code	是	代收产品标识(平台分配,如 QRPH)
amount	是	金额(该币种最小单位)
currency	是	币种(平台为你开通的,如 PHP/THB;未开通返回 1001)
subject	否	订单标题/说明
return_url	否	支付完成后跳回的页面
expire_seconds	否	有效期秒,默认 600
attach	否	原样回传的透传数据(字符串)

请求示例(sign 的计算见 签名与鉴权):

{
  "merchant_no": "M100001",
  "app_id": "app_10001",
  "key_version": 1,
  "timestamp": 1769990400,
  "nonce": "a1b2c3d4e5f6a1b2",
  "sign_type": "RSA2",
  "mch_order_no": "T20260601001",
  "product_code": "QRPH",
  "amount": 10000,
  "currency": "PHP",
  "subject": "Order 1001",
  "attach": "uid-8821",
  "sign": "BASE64_SIGNATURE"
}

响应 data 字段:

字段	说明
platform_order_no	平台订单号
mch_order_no	商户订单号
pay_url	平台支付中转页链接(用户访问后跳上游)
amount / currency	金额 / 币种
expire_at	过期时间(Unix 秒)
status	订单状态,见 订单状态

响应示例:

{
  "code": "0",
  "msg": "OK",
  "data": {
    "platform_order_no": "D20260601123456abcd",
    "mch_order_no": "T20260601001",
    "pay_url": "https://{pay-domain}/pay/r/3f9c1a7e54b04d2c",
    "amount": 10000,
    "currency": "PHP",
    "expire_at": 1769991000,
    "status": "CREATED"
  }
}

查询 POST /pay/query

请求业务参数(另带 公共参数):

字段	必填	说明
mch_order_no	二选一	商户订单号
platform_order_no	二选一	平台订单号(都传时以此为准;建议只传一个)

请求示例:

{
  "merchant_no": "M100001",
  "app_id": "app_10001",
  "key_version": 1,
  "timestamp": 1769990500,
  "nonce": "b2c3d4e5f6a1b2c3",
  "sign_type": "RSA2",
  "mch_order_no": "T20260601001",
  "sign": "BASE64_SIGNATURE"
}

响应 data 字段:

字段	说明
platform_order_no	平台订单号
mch_order_no	商户订单号
amount / currency	金额(最小单位)/ 币种
status	订单状态,见 订单状态
paid_at	支付成功时间(Unix 秒;成功时返回)
attach	透传数据(有则返回)

响应示例:

{
  "code": "0",
  "msg": "OK",
  "data": {
    "platform_order_no": "D20260601123456abcd",
    "mch_order_no": "T20260601001",
    "amount": 10000,
    "currency": "PHP",
    "status": "SUCCESS",
    "paid_at": 1769990620,
    "attach": "uid-8821"
  }
}

异步回调通知

代收订单支付成功时,平台 POST 通知到你配置的代收回调地址(Content-Type: application/json)。

• 通知体含订单结果字段 + 公共签名参数,由平台私钥签名(sign_type=RSA2)。
• 回调里的 key_version 指平台回调密钥版本(不是你的公钥版本)——用对应版本的平台公钥验签(验签方式同 签名算法)。平台公钥支持多版本轮换,请按版本保存。
• 先验签、再按 platform_order_no 幂等处理;处理成功后返回 HTTP 200 + 纯文本 success(精确小写)。
• 未收到 success 平台按递增间隔重试(15s / 1m / 5m / 30m / 2h …);同一订单可能通知多次,务必幂等。
• 请用通知里的 amount 与本地订单核对一致后再入账。

通知字段:

字段	说明
platform_order_no / mch_order_no	订单号
amount / currency	金额(最小单位)/ 币种
status	SUCCESS
paid_at	支付成功时间(Unix 秒)
attach	透传数据
key_version	平台回调密钥版本
timestamp / nonce / sign_type / sign	平台签名公共参数

通知报文示例:

{
  "platform_order_no": "D20260601123456abcd",
  "mch_order_no": "T20260601001",
  "amount": 10000,
  "currency": "PHP",
  "status": "SUCCESS",
  "paid_at": 1769990620,
  "attach": "uid-8821",
  "key_version": 1,
  "timestamp": 1769990625,
  "nonce": "f6e5d4c3b2a1f6e5",
  "sign_type": "RSA2",
  "sign": "PLATFORM_SIGN_BASE64"
}

应答(验签通过且处理成功后,HTTP 200,响应体恰为):

success

WARNING

验签不通过一律不处理、不返回 success。回调验签示例代码见 SDK 与示例。