基本规则
基本信息
所有普通 API 请求都使用 HTTPS。API 文档中的接口地址以 {apiBaseUrl} 加带版本前缀的接口 Path 展示，例如 {apiBaseUrl}/intl/v1/payment/order/create。{apiBaseUrl} 是平台下发的 HTTPS 接口域名，不能按字面值发送。测试环境和生产环境的 {apiBaseUrl} 不同；商户应先使用 测试环境完成联调，生产上线时再替换为生产环境 {apiBaseUrl}、生产商户编号、API Key 和 API Secret。生产客户端不能关闭 TLS 证书校验。
公开 v1 API 是服务端到服务端接口。请求必须由商户后端发起，不能把 API 凭据、签名逻辑或完整 收款人信息放到浏览器、移动端、小程序或前端源码中。
数据格式
POST 请求使用 JSON 请求体。GET 请求使用 Query 参数，请求体为空。请求签名原文始终使用 最终实际发出的原始请求体。
普通 API 的 POST 请求必须发送 Content-Type: application/json。 普通 API 的 GET 和 POST 请求都必须发送 Accept: application/json。普通 API 响应必须返回 Content-Type: application/json。Webhook 请求也必须发送 Content-Type: application/json。
POST 请求体最大 64 KiB。v1 公开接口不接受 XML、form-data 或 multipart payload。
JSON 字段顺序不保证稳定，也没有业务含义。商户系统必须按字段名读取响应，不能按位置读取。 金额字段使用十进制字符串，避免浮点精度问题。
创建请求里，商户只传 amount.value。所选 productCode 决定交易币种和允许的小数精度。 例如 amountScale 为 0 的币种只接受主币种整数金额，amountScale 为 2 的币种最多接受 两位小数。响应、查单结果和 Webhook 通知仍会返回 amount.currency，商户对账时不需要解析 productCode。金额格式不合法时返回 AMOUNT_FORMAT_INVALID；金额小数位超过所选产品和币种允许精度时， 返回 HTTP 422 和 AMOUNT_PRECISION_INVALID。该错误通常对应请求体里的 amount.value。
参数兼容性
平台后续版本可能增加可选响应字段，商户系统必须忽略未知响应字段。请求 Schema 会保持严格； 未知请求字段可能被拒绝。
除非字段说明明确允许，否则不要发送 null、空字符串或空数组。必填字段必须传有效值。
创建类请求按“商户编号 + merchantOrderNo”识别一笔业务订单。查询类请求只支持按 merchantOrderNo 查询。
字符集
普通 API 请求体、响应体和 Webhook Body 均使用 UTF-8 编码。避免传控制字符，以及下游清结算、 对账或排障系统无法安全保存的字符。 字段长度限制是 API 侧安全限制；即使视觉上较短，也可能因超过配置长度被拒绝。
时间格式
公开时间戳使用 Unix 秒，从 1970-01-01T00:00:00Z 起按秒计数，不携带时区且不受商户或 服务端时区影响。商户如需展示当地时间，应仅在展示层按所需时区转换。Header 中的 Timestamp 使用 Unix 秒级时间戳文本，因为 HTTP Header 的值本质上都是字符串。请求头 Timestamp 通常允许 与接口服务端时间相差 ±300 秒。
Body 中的 createTime、updateTime、expireTime 等字段使用 Unix 秒级时间戳，并以 JSON number 返回。对代收、代付订单来说， updateTime 表示当前业务 status 的生效时间。例如 status 为 SUCCEEDED 时， updateTime 就是成功时间；status 为 FAILED 时，它就是失败时间。对余额来说， updateTime 表示余额数据更新时间。公开接口版本固定为 1.0，它属于发布合同，不作为请求 Header 发送。
公共请求 Header
普通 API 请求使用独立签名 Header：
| Header | 是否必填 | 描述 |
|---|---|---|
Accept | 是 | 固定为 application/json，表示商户客户端期望接收 JSON 响应；不参与签名原文。 |
Content-Type | POST 是，GET 不发送 | POST 请求体格式固定为 application/json；不参与签名原文。 |
Api-Key | 是 | 商户后台获取的接口调用凭据。 |
Timestamp | 是 | Unix 秒级请求签名时间戳文本。 |
Nonce | 是 | 同一 API Key 下每次请求唯一的请求随机串。 |
Signature | 是 | v1= 加小写 HMAC-SHA256 十六进制请求签名；不要发送 API Secret。 |
Header 名称大小写不敏感；文档统一展示无品牌前缀的规范 Header 名，调用时不要自行添加产品、公司或品牌前缀。完整签名规则见如何签名与验签。
公共响应 Header
| Header | 返回时机 | 描述 |
|---|---|---|
Content-Type | 所有带 JSON Body 的普通 API 响应 | 固定为 application/json。 |
Request-Id | 所有普通 API 响应 | 请求追踪号，用于报障和日志关联。 |
Timestamp | 可识别 API Key 的普通 API 响应 | 响应签名时间，Unix 秒级时间戳文本。 |
Nonce | 可识别 API Key 的普通 API 响应 | 响应随机串，本次响应唯一。 |
Signature | 可识别 API Key 的普通 API 响应 | v1= 加小写 HMAC-SHA256 十六进制响应签名。 |
请求标识
所有普通 API 响应都会在响应 Header 返回 Request-Id。错误响应体会返回 error.code。可识别 API Key 的普通 API 响应还会返回 Timestamp、Nonce 和 Signature，用于按响应原始 Body 验签；无法识别 API Key 的认证失败响应可能不返回签名字段。报障时优先提供商户订单号，如有 Request-Id 响应 Header 和 响应 Body error.code，再一并提供。
报障信息只需要提供环境、请求时间、商户订单号、HTTP 状态码、Request-Id 响应 Header、 error.code；如涉及付款凭证或收款机构核实时，再提供 referenceNo。不要提供 API Secret、 Webhook Secret、签名值或完整敏感报文。
错误信息
商户系统用 HTTP 状态码判断错误大类，用 error.code 做程序分支。不要解析 error.message 执行业务逻辑，因为文案可能为了可读性调整。
普通错误响应体结构固定：
| 字段 | 描述 | 示例值 |
|---|---|---|
error.code | 稳定机器可读错误码，用于程序分支、告警聚合和排障定位。 | PARAMETER_INVALID |
error.message | 面向技术人员的安全错误描述，只作为人工阅读说明，不作为稳定程序键。 | amount.value must be a positive decimal string. |
错误码用于稳定识别发生了什么；错误描述用于解释失败原因，后续可在不改变 API 语义的情况下调整。
错误码统一使用全大写下划线格式，例如 PARAMETER_INVALID、INSUFFICIENT_BALANCE。
示例：
{
"error": {
"code": "PARAMETER_INVALID",
"message": "amount.value must be a positive decimal string."
}
}常见错误码包括参数类 PARAMETER_INVALID、签名类 INVALID_SIGNATURE、权限类 PERMISSION_DENIED、查单类 ORDER_NOT_FOUND、业务拒绝类 INSUFFICIENT_BALANCE、 频控类 FREQUENCY_LIMITED、平台异常类 INTERNAL_ERROR、明确未知创建结果 ORDER_RESULT_UNKNOWN、上游网关类 GATEWAY_ERROR 或 GATEWAY_TIMEOUT 等。
每个具体接口页面底部会列出该接口涉及的错误码、HTTP 状态码、描述和处理方式。
响应处理模型
国际版普通 API 响应按三层处理：
| 层级 | 字段 | 什么时候出现 | 含义和处理方式 |
|---|---|---|---|
| HTTP 状态码 | HTTP status | 每次普通 API 响应都有 | 200 表示接口调用成功；4xx 表示请求或业务条件被拒绝，按 error.code 处理。遇到 5xx、超时、断网或无法验证的响应时，可能无法确认订单是否已经创建；先按原 merchantOrderNo 查单，查询一段时间后仍不存在时，只能用同一单号和原请求重发。 |
| 请求错误 | error.code, error.message | HTTP 非 2xx 的错误响应体 | 表示本次 API 请求为什么失败。商户系统用 error.code 做稳定程序分支，用 error.message 给技术人员阅读。 |
| 订单状态 | status | 订单资源、查单响应和 Webhook 订单数据 | 表示代收或代付订单当前业务生命周期。商户侧订单状态应主要跟随 status。 |
| 失败原因 | failReason | 订单进入非成功最终状态时返回，例如代收 CANCELED、代付 FAILED | 面向商户运营展示或排障的安全说明。它不是第二个状态字段，商户系统仍应只用 status 判断订单状态。 |
error 和 failReason 不是同一类字段：error 说明“本次请求失败原因”，failReason 说明“订单为什么进入非成功最终状态”。例如 HTTP 200 可能返回 status=FAILED 的代付订单， 此时接口调用成功，但代付业务失败，商户可展示或查看 failReason；HTTP 422 则表示本次 创建请求被业务校验拒绝，应读取 error.code 和 error.message。
商户自定义字段与上游参考号
创建代收和代付订单时，可以按需传入 customData。referenceNo 不是商户请求字段，而是系统在订单资源和最终状态通知中返回的上游参考号：
| 字段 | 用途 | 处理规则 |
|---|---|---|
customData | 商户自定义键值对，用于把订单关联到购物车、客户、批次、内部流水等商户系统对象。 | 请求可选，最多 20 个键；键名使用 lowerCamelCase，值为字符串；会在订单资源和最终状态 Webhook 中回显，只用于商户侧关联和排障，不参与幂等、查单、路由、风控或结算。幂等重复请求返回首次受理请求保存的 customData，不会合并或覆盖。 |
referenceNo | 上游支付网络、付款机构或收款机构返回的参考号。 | 响应和通知中有值时返回，用于将付款凭证或收款核实结果关联到订单；不是商户订单号、平台订单号或渠道订单号，不参与幂等或普通查单。 |
不要在 customData 中放 API Key/API Secret、Webhook Secret、签名、认证 Token、银行卡号、完整收款银行或钱包账号、证件号、手机号、邮箱或其他敏感信息。
平台订单号
platOrderNo 继续是长度 1–32 的不透明字符串。API 查单、Webhook、数据库及对账文件均须逐字符保留原文。新部署可能返回 PHI112606010000000001001 这样的 24 位编号，末 13 位为纯数字；3002260601000001001 等历史编号仍然有效。不得增加只接受 24 位的公共输入正则，不按前缀决定权限或路由，也不转换成数字。接口环境由配置的 API 域名决定，不根据单号字符切换。
Excel 中将订单号写为文本单元格；导入 CSV 时将编号列设置为文本。机器对账文件不使用 ="..." 公式或额外前导字符。历史数字编号已被 Excel 舍入时，应重新取得原文，不猜测补全。
支付成功后返回商户
代收创建可选传 successUrl（PH pay.collect 放在 data，国际接口放在 JSON 根对象）。仅合规的 HTTPS 域名地址允许启用成功返回，无需提前登记域名。省略、null、空串、非字符串、HTTP、各种 IP 表示、其他非法地址和平台收银台同源地址均按未传处理，不因这个可选字段阻断下单。纯 QRPH 始终忽略该字段。URL 最多 2048 ASCII 字节，非 ASCII 内容须百分号编码；仅省略端口或 443，禁止用户信息、localhost、相对地址、反斜杠及控制字符。合法地址可以带路径、query、SPA fragment，平台保持原文且不追加订单或状态参数。本校验仅判断格式，不探测 DNS、网站或证书。
{"successUrl":"https://shop.example/pay/result?reference=M202609280001#done"}有效地址已保存且渠道能力已开通时，平台确认成功后显示返回按钮，并在可见页面停留 3 秒后返回商户。渠道收银台先返回平台的订单结果页；渠道返回事件及参数均不代表支付成功。国际订单须公开为 SUCCEEDED。地址被过滤时正常展示支付结果，但不展示返回按钮、不自动返回，直接访问返回入口也不会跳往商户。商户仍通过服务端查单/验签通知履约，不依赖浏览器导航；关闭页面、跨设备付款或未返回浏览器时无法保证跳转。
商户按实际发送的完整请求签名，包含原始 successUrl；平台先验签，再在业务副本中过滤，不改写验签原文。每次修改请求都须重新签名，即使修改前后的地址都会被过滤。响应不回显 successUrl 或非法地址原文，仍对实际发送的响应内容签名，商户按收到的响应原文验签。过滤不会移除用于付款的 data.url、nextAction 或二维码。
新订单以过滤后的业务参数保存快照并计算国际业务 hash：非法地址之间切换或改为未传，与未传地址等价；合法地址被改变、删除，或从无有效地址改为合法地址，仍与首次请求冲突。合法地址随首次订单冻结，返回入口最长有效至原订单创建后 7 天，不兼容变更前旧订单的摘要。同商户订单号冲突使用国际 HTTP 409 MERCHANT_ORDER_NO_CONFLICT / merchantOrderNo、PH respCode=02。无法证明原始快照时保留原单，不能使用重试参数重新下单或覆盖地址。该字段不可放入不参与幂等的 customData。