请求与响应

请求格式

正式接口均使用 POST，Content-Type: application/json。请求体为 JSON 对象；不要传 Base64 文本、JSON 字符串、XML 或表单。

timestamp 和 sign 放在请求体中。JSON 字段排列顺序不影响验签，但签名字符串必须按字段名排序。只发送该接口列出的字段。

账号、订单号等标识使用字符串，保留前导零。金额建议使用十进制字符串，例如 "500.00"，且签名时与发送时保持一致。

通用响应

多数接口使用以下结构：

{
  "request_id": "00000000-0000-4000-8000-000000000001",
  "path": "/v1/api/disbursement/create_order",
  "success": true,
  "code": 200,
  "message": "成功",
  "data": {
    "platform_order_no": "PRT202610051700DEMO0001",
    "tenant_order_no": "DEMO-PAYOUT-001",
    "amount": "500.00"
  }
}

字段	类型	含义
request_id	string	本次请求的排查标识
path	string	请求路径
success	boolean	本次接口操作是否成功，不是付款成功标志
code	integer	接口结果码，不是订单状态
message	string	说明文字；可能为中文或英语，不应作为程序判断条件
data	object	接口数据；错误时可不存在

例外：UPI 查询和UTR 查询成功响应使用 status / timestamp / message / body，不使用 success / code / data。这两个接口的验证错误仍可能使用通用错误结构。

HTTP 状态与业务码

情况	当前 HTTP 表现	判定依据
请求正常完成	通常 200	同时检查响应体，不能只看 HTTP 200
显式 OpenAPI 参数／业务异常	可为 200	success=false 与 code
查单未找到（203006）	当前为 500	这是查询结果码，不是付款状态
限速	429	code=100429、Retry-After
未预期异常	500	通常 code=100500；保留 request_id 排查

不要假设所有业务错误都返回 200，也不要把所有 HTTP 500 都当成同一种错误。收到超时、网络断开或结果不明时，应通过原订单号查单确认，而不是仅凭 HTTP 状态判定付款失败。