商户 OpenAPI 接入文档

• Base URL：请登录商户后台「安全中心 · OpenAPI」获取你的实际接入地址（本文示例中以 <BASE_URL> 占位）。
• 接口版本：v1（服务端版本 1.2.0；每次响应都带 X-Api-Version 头）
• 导出日期：20260623

注意：本文档不包含商户真实凭据与白名单信息，请使用占位符替换后对接。

版本与兼容策略

• 大版本体现在路径前缀：当前为 /api/open/v1。
• v1 仅做向后兼容的演进（新增可选字段、修复缺陷），不会改变已有字段含义或收紧已有校验。
• 若有破坏性变更，会新增 /api/open/v2 并保留 v1 一段时间，商户可平滑迁移。
• 可调用 GET <BASE_URL>/version 查询当前服务端版本（无需鉴权）。

本次变更（1.2.0）：

• 代收对外 status 不再返回 expired：超时未支付统一归一为 pending（处理中），请以查单结果为准。
• 代收仅在订单成功（success）时回调商户；失败/超时等非成功状态不回调，商户应通过查单接口获知最终结果（代付不受此限制）。

商户信息

• 商户名称：<YOUR_MERCHANT_NAME>
• 商户号：<YOUR_MERCHANT_NO>

官方 SDK

提供 5 种语言的官方 SDK：零第三方依赖（仅用各语言标准库），内置 HMAC-SHA256 请求签名 / 回调验签、测试与正式双环境（SANDBOX 本地 / PRODUCTION 传你的专有域名 baseUrl）、覆盖全部接口，且跨语言签名逐字节一致。推荐直接使用 SDK 完成对接，无需自行实现签名与稳定序列化。

• 仓库与发布说明：https://github.com/bebebus/SDK （签名算法权威说明见仓库 SIGNING.md，端点字段级请求/响应见 INTERFACES.md）。

代收：创建订单（pay/create）

• 方法：POST
• 接口：<BASE_URL>/merchant/pay/create
• 用途：创建代收订单，返回平台订单号与支付链接/二维码内容。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign、out_order_no、amount、currency、pay_method、notify_url
• 可选字段：nonce、country、return_url、subject、remark、client_ip、extra

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "out_order_no": "202501010001",
  "amount": 10000,
  "currency": "PHP",
  "pay_method": "gcash",
  "country": "PH",
  "notify_url": "https://merchant.example.com/api/notify/pay",
  "return_url": "https://merchant.example.com/pay/result",
  "subject": "订单标题（可选）",
  "remark": "备注（可选）",
  "client_ip": "1.2.3.4",
  "extra": {
    "user_id": "u123456",
    "customer": {
      "first_name": "San",
      "last_name": "Zhang",
      "email": "[email protected]",
      "phone": "13800000000"
    }
  }
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "order_no": "P20250101000001",
    "out_order_no": "202501010001",
    "amount": 10000,
    "currency": "PHP",
    "pay_url": "https://pay.example.com/h5/P20250101000001",
    "qrcode_content": "https://pay.example.com/h5/P20250101000001",
    "pay_params": null,
    "expire_at": "2025-01-01T12:30:00Z",
    "status": "pending"
  }
}

补充说明

• 金额 = 实际金额 × 10000 的整数，例如 1.2345 传 12345，以整数传输避免浮点误差。
• 幂等键：同一商户的 out_order_no 全局唯一；重复下单参数一致视为幂等成功，参数不一致返回幂等冲突。
• 上游未受理时接口实时返回 code=100000 且订单置 failed 终态；此时不可用相同 out_order_no 重试（幂等只会返回该 failed 单），需换新 out_order_no 重新下单。
• 【用户信息（强烈建议必传）】gcash/maya 等主流支付方式的上游渠道实际强制要求下单用户的姓名/手机（email 部分渠道可选），缺失会被上游拒单导致订单失败；平台侧不再以 300405 拦截（customer 选填，提供时做格式校验+整名自动拆分）。请用通用字段提供，平台会自动映射到各渠道所需格式（例如把整名拆成 first/last_name）：姓名——extra.customer.name 整名（也可显式 extra.customer.first_name+last_name）；邮箱——extra.customer.email（或 extra.email）；手机——extra.customer.phone（或 extra.phone）。这样商户只需接一套通用字段，无需为每个渠道单独适配。
• 【支付原生串】pay_url 为空而 pay_params 非空时（部分支付方式仅返回原生唤端参数），请在客户端用 pay_params 唤起支付。

常见错误

• 100101 请求过期
• 100102 IP 不在白名单
• 100104 签名错误
• 100105 IP 在黑名单
• 100000 创建订单失败（上游未受理，订单已实时置 failed）
• 300404 无可用支付方式渠道（country/currency/pay_method 未命中可用上游）
• 100001 参数校验失败（如 notify_url 指向内网/非法协议）
• 300402 上游配置不可用
• 300403 费率未配置

代收：查询订单（pay/query）

• 方法：POST
• 接口：<BASE_URL>/merchant/pay/query
• 用途：按平台订单号或商户订单号查询代收订单状态。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign、order_no/out_order_no（二选一）
• 可选字段：nonce

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "out_order_no": "202501010001",
  "order_no": null
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "order_no": "P20250101000001",
    "out_order_no": "202501010001",
    "amount": 10000,
    "currency": "USDT",
    "status": "success",
    "channel_order_no": "CH20250101XXX",
    "paid_at": "2025-01-01T12:15:00Z",
    "notify_status": "success"
  }
}

补充说明

• order_no/out_order_no 至少提供一个。
• status 终态为 success/failed；pending 表示处理中（含超时未支付，已统一归一为 pending）。
• 代收仅在订单成功（success）时回调商户；失败/超时等非成功状态不回调，商户应通过本查单接口获知最终结果。

常见错误

• 100104 签名错误
• 300301 订单不存在

代付：创建订单（payout/create）

• 方法：POST
• 接口：<BASE_URL>/merchant/payout/create
• 用途：创建代付订单并冻结余额（创建成功不代表最终出款成功）。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign、out_payout_no、amount、currency、pay_method、notify_url、account_no
• 可选字段：nonce、country、account_name、bank_name、bank_code、remark、client_ip、extra

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "out_payout_no": "WD202501010001",
  "amount": 5000,
  "currency": "PHP",
  "pay_method": "gcash",
  "country": "PH",
  "notify_url": "https://merchant.example.com/api/notify/payout",
  "account_name": "张三（可选）",
  "account_no": "09171234567",
  "bank_name": "可选：银行卡代付时填银行名（gcash 等钱包类可省略）",
  "client_ip": "1.2.3.4",
  "remark": "商户提现（可选）",
  "extra": {
    "user_id": "u123456",
    "customer": {
      "first_name": "San",
      "last_name": "Zhang",
      "email": "[email protected]",
      "phone": "13800000000"
    }
  }
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "payout_no": "W20250101000001",
    "out_payout_no": "WD202501010001",
    "amount": 5000,
    "currency": "PHP",
    "status": "pending",
    "review_status": "pending",
    "fee_amount": 20,
    "freeze_amount": 5020
  }
}

补充说明

• 创建成功表示"已受理并冻结余额"。代付通常需要审核/下发等流程，最终结果以异步通知与查询为准。
• 幂等键：同一商户的 out_payout_no 全局唯一；重复下单参数一致视为幂等成功。
• 【用户信息（强烈建议必传）】gcash/maya 等主流支付方式的上游渠道实际强制要求下单用户的姓名/手机（email 部分渠道可选），缺失会被上游拒单导致订单失败；平台侧不再以 300405 拦截（customer 选填，提供时做格式校验+整名自动拆分）。请用通用字段提供，平台会自动映射到各渠道所需格式（例如把整名拆成 first/last_name）：姓名——代付可用 account_name（收款人/账户名，自动映射为 last_name），或 extra.customer.name 整名（也可显式 extra.customer.first_name+last_name）；邮箱——extra.customer.email（或 extra.email）；手机——extra.customer.phone（或 extra.phone）。这样商户只需接一套通用字段，无需为每个渠道单独适配。
• 【银行类代付】pay_method 为银行类时 bank_code 必传，取值用「查询可用银行（payout/banks/query）」接口返回的 code；编码非法返回 300407。

常见错误

• 100104 签名错误
• 300201 代付下单幂等冲突
• 300501 余额不足
• 300404 无可用支付方式渠道
• 300403 费率未配置
• 300401 渠道不可用/不存在
• 100001 参数校验失败（如 notify_url 指向内网/非法协议）
• 300402 上游配置不可用
• 300406 缺少必要下单参数（如 bank_code）
• 300407 银行编码非法

代付：查询订单（payout/query）

• 方法：POST
• 接口：<BASE_URL>/merchant/payout/query
• 用途：按平台代付单号或商户代付单号查询代付订单状态。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign、payout_no/out_payout_no（二选一）
• 可选字段：nonce

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "payout_no": null,
  "out_payout_no": "WD202501010001"
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "payout_no": "W20250101000001",
    "out_payout_no": "WD202501010001",
    "amount": 5000,
    "currency": "USDT",
    "status": "success",
    "sub_state": null,
    "channel_order_no": "CHW20250101XXX",
    "finished_at": "2025-01-01T13:00:00Z",
    "failed_reason": null,
    "notify_status": "success"
  }
}

补充说明

• payout_no/out_payout_no 至少提供一个。
• status 终态为 success/failed；pending 表示处理中（请继续等待回调或轮询查单）。
• sub_state 是处理中状态的归一化细分（verifying 表示出款结果核实中，仍是非终态）；sub_state 仅用于展示/排查，业务判断以 status 终态（success/failed）为准。

常见错误

• 100104 签名错误
• 300301 订单不存在

代付：查询可用银行（payout/banks/query）

• 方法：POST
• 接口：<BASE_URL>/merchant/payout/banks/query
• 用途：按国家 + 支付方式查询当前可用的银行列表（银行类代付下单 bank_code 的合法取值）。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign、pay_method
• 可选字段：nonce、country、currency

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "pay_method": "bank",
  "country": "PH",
  "currency": "PHP"
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "banks": [
      {
        "code": "BDO",
        "name": "BDO Unibank"
      },
      {
        "code": "BPI",
        "name": "Bank of the Philippine Islands"
      },
      {
        "code": "GCASH",
        "name": "GCash"
      },
      {
        "code": "MAYA",
        "name": "Maya"
      }
    ]
  }
}

补充说明

• 银行列表随上游渠道可用性动态变化，建议下单前实时查询（或做短期缓存）。
• 纯钱包类支付方式（pay_method=gcash/maya 本身）无需选目的地，返回空 banks；银行类（pay_method=bank）的 banks 可能含电子钱包（如 GCASH/MAYA）作为代付目的地，bank_code 可传其 code。

常见错误

• 100104 签名错误

代付：查询付款凭证（payout/proof/query）

• 方法：POST
• 接口：<BASE_URL>/merchant/payout/proof/query
• 用途：查询已成功代付订单的上游付款凭证地址（并非所有渠道/币种都提供凭证）。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign、payout_no/out_payout_no（二选一）
• 可选字段：nonce

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "payout_no": null,
  "out_payout_no": "WD202501010001"
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "payout_no": "W20250101000001",
    "out_payout_no": "WD202501010001",
    "proof_url": "https://proof.example.com/xxx.pdf",
    "expires_in": 1800,
    "queried_at": "2025-01-01 13:00:00"
  }
}

补充说明

• 仅出款成功（status=success）的订单可查凭证；处理中/失败订单返回 300409。
• 并非所有渠道/币种都提供凭证；部分渠道仅支持查询近几天内的订单（超窗返回 300409）。
• 凭证 URL 有访问时效（expires_in 秒），请下载转存而非保存 URL。

常见错误

• 100104 签名错误
• 300301 订单不存在
• 300408 渠道不支持凭证查询
• 300409 凭证暂不可用

代付：查询付款收据图片（payout/receipt/query）

• 方法：POST
• 接口：<BASE_URL>/merchant/payout/receipt/query
• 用途：查询/生成代付订单的付款收据图片（PNG）。仅 status=success 的代付单可生成；render-once 落盘复用。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign、payout_no/out_payout_no（二选一）
• 可选字段：nonce、lang、inline

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "payout_no": null,
  "out_payout_no": "WD202501010001",
  "lang": "zh-CN",
  "inline": 0
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "payout_no": "W20250101000001",
    "out_payout_no": "WD202501010001",
    "lang": "zh-CN",
    "receipt_url": "/api/open/v1/payout/receipt/file?token=eyJhbGciOiJIUzI1NiJ9...",
    "expires_in": 3600
  }
}

补充说明

• 仅出款成功（status=success）的代付单可生成收据；非 success 状态返回 300410。
• render-once：首次生成后图片落盘复用，相同参数重复查询直接返回缓存结果。
• lang 不传时平台按订单国家自动派生语言（如 PH → en）；显式指定可覆盖。
• inline=1 时响应体直接含 Base64 图片（image_base64 + mime），适合服务端即时处理；inline=0（默认）时返回带时效签名的 receipt_url 下载链接，适合前端跳转/嵌入。
• 下载链接有时效（expires_in 秒），请勿持久化 URL；需长期保存请下载图片转存至自有存储。

常见错误

• 100104 签名错误
• 300301 订单不存在
• 300410 代付收据暂不可用（订单非 success）
• 300411 收据生成失败

通用：查询可用支付方式（pay-methods/query）

• 方法：POST
• 接口：<BASE_URL>/merchant/pay-methods/query
• 用途：查询平台启用的支付方式字典（下单 pay_method/country 的合法取值）。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign
• 可选字段：nonce、country

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "country": "PH"
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "methods": [
      {
        "pay_method": "gcash",
        "name": "GCash",
        "country": "PH",
        "currency": "PHP"
      },
      {
        "pay_method": "maya",
        "name": "Maya",
        "country": "PH",
        "currency": "PHP"
      }
    ]
  }
}

补充说明

• 返回的是平台启用的支付方式字典；某支付方式当下是否有可用上游以下单接口实际返回为准（无可用渠道时报 300404）。

常见错误

• 100104 签名错误

通用：查询账户余额（balance/query）

• 方法：POST
• 接口：<BASE_URL>/merchant/balance/query
• 用途：查询商户交易账户各币种的可用/冻结余额。

请求说明

• Content-Type：application/json
• 必填字段：merchant_no、api_key、timestamp、sign
• 可选字段：nonce、currency

请求示例

{
  "merchant_no": "<YOUR_MERCHANT_NO>",
  "api_key": "<YOUR_API_KEY>",
  "timestamp": 1736073600,
  "nonce": "random-xyz",
  "sign": "<SIGN>",
  "currency": "PHP"
}

签名说明：sign 需对"请求 JSON 顶层除 sign 以外的所有字段"参与计算；object/array 字段会按稳定 JSON 序列化。

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "balances": [
      {
        "currency": "PHP",
        "available": 12345600,
        "frozen": 50000
      }
    ]
  }
}

补充说明

• available 为可用余额，frozen 为冻结金额（含在途代付冻结）；均为最小单位整数。

常见错误

• 100104 签名错误

通用：服务版本（GET /version）

• 方法：GET
• 接口：<BASE_URL>/version
• 用途：查询服务端 OpenAPI 版本（无需鉴权）；所有 /api/open/ 响应均带 X-Api-Version 头。

请求说明

• Content-Type：application/json
• 必填字段：无
• 可选字段：无

无

请求示例

{}

返回字段与示例

• 统一返回结构：{ code, message, data }；业务失败通常仍为 HTTP 200。

返回示例

{
  "code": 0,
  "message": "ok",
  "data": {
    "major": "v1",
    "version": "1.2.0",
    "base_path": "/api/open/v1"
  }
}

补充说明

• 无需鉴权；用于探活与版本灰度排查。

签名与通用字段

通用字段（建议放在 JSON 请求体中）：merchant_no、api_key、timestamp、nonce（可选）、sign。 建议算法：HMAC-SHA256。把所有参与签名字段（不含 sign）按字段名 ASCII 升序排序，拼成 key=value 并用 & 连接，末尾追加 &secret=...，对 raw string 做 HMAC-SHA256，结果转 16 进制小写作为 sign。 时间戳窗口为 ±300 秒（请求时间与服务端相差超过此范围返回 100101）。防重放：传 nonce 时按 nonce 去重，不传时按「签名指纹」兜底去重；两类去重记录均保留 300 秒，即同一 nonce / 同一已签名请求在 300 秒内不可重复（重复返回 100103）。建议为每个请求生成全局唯一 nonce（如 UUID），并保证其在至少 300 秒内不重复。

提示：以上签名规则已由「官方 SDK」内置实现，对接时直接调用 SDK 即可，无需手写签名与稳定序列化。

金额口径

所有金额统一约定为 金额 = 实际金额 × 10000 的整数（最小记账单位 0.0001），例如 1.2345 传 12345，以整数传输避免浮点误差。该口径适用于全部请求、响应与回调的金额字段，且不区分币种（请勿按「元」理解）。

回调说明

平台会按订单创建时的 notify_url 以 POST application/json 方式回调支付/代付结果。 回调同样携带签名字段，请商户侧按对应业务（pay/payout）使用各自密钥验签。

代收回调时机：代收仅在订单成功（status=success）时回调商户；失败/超时等非成功状态不回调，商户应通过查单接口（pay/query）获知最终结果。 （代付不受此限制：代付在终态 success/failed 均会回调。）

成功应答规则：商户处理成功后，必须返回 HTTP 200 且响应体为 success 或 ok（大小写不敏感）； 也接受 JSON 格式：{"success":true} / {"code":0} / {"message":"success"} / {"message":"ok"}。 未按此返回（即使 HTTP 200 但 body 为其他内容，如空响应、HTML 错误页等）平台视为回调失败， 将按策略重试，连续失败达阈值会触发告警。

代收回调字段

代付回调字段

注意：代付回调体不包含 notify_status。notify_status 只是「查单返回」里平台→商户的推送状态字段，不会出现在回调体中。

回调签名验证

回调验签算法与请求签名完全一致（见「签名与通用字段」一节）：

1. 取回调 JSON 顶层「除 sign 外、且值非 null」的所有字段；
2. 按字段名 ASCII（码点）升序排序，拼成 key=value 用 & 连接；
3. 末尾追加 &secret=<对应密钥>，对该 raw string 做 HMAC-SHA256，输出 16 进制小写；
4. 与回调体的 sign 比对（建议用常量时间比较，如 crypto.timingSafeEqual，防时序攻击）。

密钥选择：代收回调用 api_secret_pay，代付回调用 api_secret_payout。channel_order_no 等值为 null 的字段不参与签名（与请求签名「跳过 null」一致）。

安全红线（务必遵守）：① 先验签通过、再处理业务与入账，严禁未验签即按回调内容改单；② 入账 / 对账金额以 actual_amount（用户实付）与 net_amount（净入账 = 实付 − 手续费）为准，切勿使用 amount（仅为下单参考额）；③ 回调可能因重试重复投递，请按 out_order_no / out_payout_no 幂等处理，重复通知不可重复入账；④ 平台回调来源 IP 不固定（云端部署，出口 IP 动态），请勿用 IP 白名单限制回调来源——验签是唯一可信校验。

重试 / 超时 / 告警 / 安全

• 超时：平台等待商户应答 8000ms，无应答即判本次失败。
• 重试：最多 6 次（含首次），退避间隔依次约 1分钟 / 2分钟 / 5分钟 / 10分钟 / 30分钟 / 60分钟（超过取最后一档）；达上限仍失败则该回调任务置 failed，商户可用查单接口兜底获取终态。
• 告警：连续失败达阈值（3 次）触发平台侧站内信告警（运营介入排查），不影响商户侧重试。
• 不跟随重定向：平台对 notify_url 不跟随 30x 重定向（安全加固）。
• SSRF 防护：notify_url 指向内网 / 环回 / 链路本地地址会被拦截，直接判失败且不重试（地址不会自行变化）；下单时此类 notify_url 亦会返回 100001。

字段口径与对外约定

• 回调金额同请求口径：= 实际金额 × 10000 的整数。
• status 为对外归一形态（非内部真实值）：代收恒为 success；代付为 success/failed。

代收 vs 代付差异

• 触发时机：代收仅在 success 时触发回调；代付在终态 success/failed 均触发。
• 字段差异：代收特有 actual_amount / net_amount / paid_at；代付特有 finished_at / failed_reason。

IP 黑白名单说明

• 默认不启用白名单（允许所有来源 IP 访问 OpenAPI）。
• 当启用策略后，命中黑名单直接拒绝；存在白名单时必须命中白名单才允许访问。
• 导出文档不包含商户真实白名单配置，请在商户后台自行查看。

错误码总表

所有业务错误统一返回 HTTP 200 + 信封 { code, message, data }，不使用 HTTP 4xx/5xx 表达业务失败（传输层 4xx/5xx 仅代表网络/网关异常，应排查链路或重试）。各端点「常见错误」只列高频项，完整错误码以本表为准；鉴权类错误（100xxx）对所有需鉴权端点通用。

频率限制与轮询建议

• 限流仅作用于鉴权失败：同一 merchant_no + 来源 IP 在 60 秒内鉴权失败累计达 60 次后，后续请求被拒并返回 100106，窗口滚动恢复（约 60 秒）。成功鉴权的正常业务请求无 QPS 硬上限。
• 不要无退避地重试鉴权失败（签名错误、时间偏移等），否则极易触发 100106；先修正原因再请求。
• 查单轮询建议：终态优先依赖回调；未收到回调时再轮询查单，并使用指数退避（例如首次延迟 3~5 秒，随后 5s → 15s → 30s → 60s 递增，直至终态或合理上限）。避免对未终态订单高频空轮询；代付查单涉及上游同步，请更克制。

对接须知

• 入账金额以 actual_amount 为准：代收按用户实付金额入账与对账，请以回调 / 查单中的 actual_amount（实付）与 net_amount（净入账 = 实付 − 手续费）为准；amount 仅为下单参考额，不可作为入账依据。
• 金额上下限：各 pay_method / 渠道的金额上下限由平台按渠道实时校验，不预先公布固定值；超限下单会返回相应错误码（如 300402 / 300404）。请勿在客户端硬编码金额区间。
• 订单有效期：代收订单 expire_at 由平台配置（并可能按订单覆盖），请以下单返回的 expire_at 为准，不要硬编码固定时长；超时未支付对外统一归一为 pending，以查单结果为准。
• 回调来源：平台回调出口 IP 不固定，请勿用 IP 白名单限制回调来源，以验签作为唯一可信校验（见「回调签名验证」与上方安全红线）。