商户接口文档

本文面向第一次对接的商户程序员。文中的 https://api.example.com 是示例地址，所有接口路径都以 /v1 开头。实际的接口网关、商户后台地址、AppID 和平台的通知来源 IP，请登录商户后台在「对接资料」页面查看，或者看上级发给你的对接信息。

1. 对接步骤

1. 拿到 AppID 和密钥。由平台或你的上级在商户后台为你生成一组 API 凭证：app_id（形如 app_xxxxxxxxxxxxxxxx）和密钥（64 位十六进制字符串）。密钥明文只在生成时显示一次，之后只能看到指纹，请立即保存到服务端的配置或密钥管理系统中，不要写进前端代码、App 安装包或代码仓库。
2. 在商户后台设置 IP 白名单。登录商户后台，把你服务器调用接口时使用的出口公网 IP 填进这把密钥的白名单。设置白名单后，其他 IP 即使拿到密钥也无法调用（返回 403 IP_NOT_ALLOWED）。代付接口强制要求设置白名单，没设置时返回 403 IP_WHITELIST_REQUIRED。
3. 下单。按 签名 规则给请求签名，调用 下单接口。把返回的 cashier_url（收银页链接）或 pay_payload 交给用户去支付。用 在线签名调试器 或 SDK 可以快速验证签名是否正确。
4. 处理通知。订单状态变化后，平台会向你下单时填的 notify_url 发送签名的 HTTP POST 通知。你的服务要验签、按 event_id 去重、更新自己的订单，然后返回 HTTP 2xx。详见 事件通知。如果平台出口 IP 需要加到你的防火墙白名单，见 出口 IP。
5. 查询兜底。通知可能延迟或丢失（你的服务宕机、网络不通）。对长时间没有收到通知的订单，用 查询接口 主动查询，以查询结果为准。调用接口超时时，用同一个商户单号查询或重试，不要换单号重新下单。

2. 通用约定

3. 签名

3.1 请求签名

签名覆盖整个请求体，不需要对 JSON 字段排序或拼接。先拼出待签名串，再用密钥做 HMAC-SHA256：

待签名串 = 大写METHOD + "\n" + PATH + "\n" + 排序后的QUERY + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + hex(sha256(BODY))
签名     = hex(HMAC-SHA256(密钥, 待签名串))      // 小写十六进制

• METHOD：GET 或 POST，大写。
• PATH：实际请求 URL 的路径部分，不含域名和查询串，例如 /v1/payin/orders。如果你的网关地址带路径前缀，PATH 要包含这个前缀。
• 排序后的QUERY：先按参数名排序，同名参数再按值排序（按 UTF-8 字节序）。每项写成 编码(名)=编码(值)，用 & 连接。没有查询参数时是空串（待签名串里该行为空行）。
• TIMESTAMP、NONCE：和请求头 X-Timestamp、X-Nonce 的值完全相同。
• BODY：请求体的原始字节。没有请求体（GET 请求，或没有请求体的 POST）时是空串，空串的 sha256 照常参与，值为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。
• 密钥按 UTF-8 字符串使用，也就是直接把 64 位十六进制字符串当作密钥文本，不要先把它解码成二进制。

查询串的编码规则

和 Go 语言的 url.QueryEscape 完全一致：

• A-Z a-z 0-9 - _ . ~ 不编码。
• 空格编码为 +。
• 其他字节（中文按 UTF-8 字节）编码为 %XX，十六进制用大写。例如 * 编码为 %2A，中 编码为 %E4%B8%AD。

请求体签名用的字节必须和实际发出的字节完全一致：先把请求对象序列化成 JSON 字符串，再用这个字符串计算签名并原样发送。JSON 序列化时不必转义中文和 /（转义了也能验签，只是日志不易读）。

3.2 完整示例

下面是一个可以直接对照的示例，调试器里点“载入示例”可以得到相同的结果。

密钥（示例用，不是真实密钥）：

0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

请求：POST /v1/payin/orders，X-Timestamp: 1767225600，X-Nonce: n0nce-0000000001，没有查询参数。请求体（一行，无多余空白）：

{"out_trade_no":"M202601010001","product_code":"ALIPAY_H5","amount":10000,"subject":"测试商品","notify_url":"https://m.example.com/notify"}

第 1 步，计算请求体的 sha256（十六进制小写）：

8ea26eef89ccd7f6c7624fe428283f32d9af2db43327e505f3f124ccba52427c

第 2 步，按顺序用换行符 \n 连接 6 项（第 3 行是空的，因为没有查询参数），得到待签名串，共 6 行：

POST
/v1/payin/orders

1767225600
n0nce-0000000001
8ea26eef89ccd7f6c7624fe428283f32d9af2db43327e505f3f124ccba52427c

注意第 3 行是空行（排序后的 QUERY 为空），不含任何字符；最后一行结尾没有换行符。

第 3 步，用密钥对待签名串做 HMAC-SHA256，得到签名：

d596c056bc211383eb3c208fb707a234931c7c7660f919a7af9dbf5d195cd547

第 4 步，发送请求：

POST https://api.example.com/v1/payin/orders
Content-Type: application/json
X-App-Id: app_xxxxxxxxxxxxxxxx
X-Timestamp: 1767225600
X-Nonce: n0nce-0000000001
X-Signature: d596c056bc211383eb3c208fb707a234931c7c7660f919a7af9dbf5d195cd547

{"out_trade_no":"M202601010001","product_code":"ALIPAY_H5","amount":10000,"subject":"测试商品","notify_url":"https://m.example.com/notify"}

带查询参数的例子：GET /v1/payouts?z=2&out_trade_no=A+B~C%2A%E4%B8%AD&a=b&a=a&empty=，“排序后的 QUERY”是 a=a&a=b&empty=&out_trade_no=A+B~C%2A%E4%B8%AD&z=2（时间戳 1767225600，Nonce n0nce_0000000003，签名 7228739edeaf0c6dff64ee73d745163a60d54faf5c4db6cc3c1ae8e98410b0a2）。其中参数值 A B~C*中 的空格、*、中文都按上面的规则编码。这个例子也在页面加载时用来自检调试器，见下一节。

没有请求体的 POST（关闭订单）：POST /v1/payin/orders/P2026010100000001/close，不要发送请求体，待签名串里 BODY 部分用空串的 sha256。

3.3 响应验签

验签通过的请求，平台的响应带 3 个头：X-Signature、X-Timestamp、X-Request-Id。响应的待签名串是 4 行：

响应待签名串 = HTTP状态码 + "\n" + X-Request-Id + "\n" + X-Timestamp + "\n" + hex(sha256(响应体原始字节))
签名         = hex(HMAC-SHA256(密钥, 响应待签名串))

示例（HTTP 200，X-Request-Id: 01JGZ8Q4R5S6T7V8W9X0Y1Z2A3，X-Timestamp: 1767225600，响应体 {"code":"OK","message":"","request_id":"01JGZ8Q4R5S6T7V8W9X0Y1Z2A3","data":{"order_no":"P1"}}）：

200
01JGZ8Q4R5S6T7V8W9X0Y1Z2A3
1767225600
bd1480965b3c4bdcaed90c0f5fe83abae05e010d2cf2740dfcf6866f91b4370c

对应签名 0cee6bfb3f7566624bc5e28aecee85e5789038652546252046fd8483c04a0de9。响应带 X-Signature 时建议验签，不一致就丢弃这次响应，不要使用里面的数据。响应体要用收到的原始字节计算，不要先解析再重新序列化。

4. 在线签名调试器

填入和你的请求相同的内容，就能看到排序后的查询串、待签名串和签名，用来和你程序算出的结果对比。密钥只在你的浏览器里计算，不会发送出去：本页的调试器不发起任何网络请求，计算使用浏览器自带的 WebCrypto（HMAC-SHA256、SHA-256）。即便如此，仍建议只在这里使用测试密钥。

5. 接口

下面每个接口的请求都要按 签名 规则带 4 个请求头。表格里“必填”列为“是”的字段不能缺少。

POST5.1 下单

POST https://api.example.com/v1/payin/orders

请求字段

请求示例

{
  "out_trade_no": "M202601010001",
  "product_code": "ALIPAY_H5",
  "amount": 10000,
  "subject": "测试商品",
  "notify_url": "https://m.example.com/notify",
  "return_url": "https://m.example.com/return",
  "client_ip": "203.0.113.8",
  "attach": "uid=1001",
  "expire_seconds": 900
}

响应字段（data）

下单、查询订单、关闭订单返回相同结构：

响应示例

{
  "code": "OK",
  "message": "",
  "request_id": "01JGZ8Q4R5S6T7V8W9X0Y1Z2A3",
  "data": {
    "order_no": "P2026010100000001",
    "out_trade_no": "M202601010001",
    "status": "pending",
    "order_amount": 10000,
    "pay_amount": 10000,
    "pay_payload": {"pay_url": "https://pay.example.com/xxxx"},
    "cashier_url": "https://cashier.example.com/c/xxxx",
    "expire_at": "2026-01-01T08:15:00+08:00",
    "final_close_at": "2026-01-01T08:20:00+08:00"
  }
}

可能的错误码：INVALID_PARAM、MERCHANT_FROZEN、PAYIN_DISABLED、PRODUCT_NOT_ENABLED、RISK_REJECTED、CHANNEL_UNAVAILABLE、FEE_NOT_CONFIGURED、DUPLICATE_OUT_TRADE_NO、SERVICE_UNAVAILABLE，见 错误码。

GET5.2 查询订单

GET https://api.example.com/v1/payin/orders/{order_no}
GET https://api.example.com/v1/payin/orders?out_trade_no={out_trade_no}

按平台订单号或你的商户单号查询。没有请求体。用商户单号查询时，参数名是 out_trade_no，缺少时返回 400 INVALID_PARAM。响应字段和 下单 相同；订单待支付时响应带 cashier_url。订单不存在或不属于你返回 404 ORDER_NOT_FOUND。

{
  "code": "OK",
  "message": "",
  "request_id": "01JGZ8Q4R5S6T7V8W9X0Y1Z2A5",
  "data": {
    "order_no": "P2026010100000001",
    "out_trade_no": "M202601010001",
    "status": "paid",
    "order_amount": 10000,
    "pay_amount": 10000,
    "expire_at": "2026-01-01T08:15:00+08:00",
    "final_close_at": "2026-01-01T08:20:00+08:00",
    "paid_at": "2026-01-01T08:03:21+08:00"
  }
}

POST5.3 关闭订单

POST https://api.example.com/v1/payin/orders/{order_no}/close

商户主动关闭待支付订单。没有请求体，签名时 BODY 用空串。返回关单后的订单（结构同下单响应），状态有几种可能：

• closed：已关闭。
• expired：部分通道不支持立即撤销，订单先进入已过期，等到 final_close_at（宽限期结束）后变成 closed。
• paid：关闭前发现用户其实已经付款，订单状态为已支付，请按已支付处理。

订单已经是 closed、expired、failed 时重复关闭，直接返回当前状态。订单已支付（含部分退款、全额退款）时返回 409 ORDER_NOT_CLOSABLE，需要退款请用 退款接口；订单正在提交上游（created）时也返回 ORDER_NOT_CLOSABLE，稍后重试。订单最终关闭时会收到 payin.closed 通知。

POST5.4 申请退款

POST https://api.example.com/v1/refunds

支持部分退款，用 out_refund_no 保证幂等。同一张订单同一时间只能有一笔退款在处理中。

请求字段

{
  "order_no": "P2026010100000001",
  "out_refund_no": "RF202601010001",
  "amount": 3000,
  "reason": "用户申请退款"
}

响应字段（data）

{
  "code": "OK",
  "message": "",
  "request_id": "01JGZ8Q4R5S6T7V8W9X0Y1Z2A6",
  "data": {
    "refund_no": "R2026010100000001",
    "out_refund_no": "RF202601010001",
    "order_no": "P2026010100000001",
    "out_trade_no": "M202601010001",
    "amount": 3000,
    "status": "processing",
    "created_at": "2026-01-01T09:00:00+08:00"
  }
}

可能的错误码：INVALID_PARAM、ORDER_NOT_FOUND、ORDER_NOT_REFUNDABLE、REFUND_NOT_SUPPORTED、REFUND_IN_PROGRESS、REFUND_AMOUNT_EXCEEDED、INSUFFICIENT_BALANCE、DUPLICATE_OUT_REFUND_NO。

GET5.5 查询退款

GET https://api.example.com/v1/refunds/{refund_no}
GET https://api.example.com/v1/refunds?out_refund_no={out_refund_no}

没有请求体，响应字段同 申请退款。退款单不存在或不属于你返回 404 REFUND_NOT_FOUND。

POST5.6 代付手续费试算

POST https://api.example.com/v1/payouts/fee-quote

按当前生效的费率试算，不冻结资金、不生成订单。

响应字段（data）

请求：
{"product_code": "BANK_PAYOUT", "amount": 50000}

响应：
{
  "code": "OK",
  "message": "",
  "request_id": "01JGZ8Q4R5S6T7V8W9X0Y1Z2A7",
  "data": {
    "amount": 50000,
    "fee": 300,
    "fee_mode": "external",
    "hold_amount": 50300,
    "payee_amount": 50000
  }
}

可能的错误码：INVALID_PARAM（金额不大于 0，或内扣时手续费超过金额）、PAYOUT_DISABLED、PRODUCT_NOT_ENABLED。

POST5.7 发起代付

POST https://api.example.com/v1/payouts

请求字段

{
  "out_trade_no": "W202601010001",
  "product_code": "BANK_PAYOUT",
  "amount": 50000,
  "payee": {
    "name": "张三",
    "account": "6222020200112233445",
    "type": "personal",
    "bank_code": "ICBC",
    "bank_name": "中国工商银行"
  },
  "notify_url": "https://m.example.com/payout-notify",
  "attach": "batch=7"
}

卡号和姓名平台收到后立即加密保存，响应和查询只返回打码后的姓名和卡号后四位。

响应字段（data）

发起代付和查询代付返回相同结构：

{
  "code": "OK",
  "message": "",
  "request_id": "01JGZ8Q4R5S6T7V8W9X0Y1Z2A8",
  "data": {
    "order_no": "D2026010100000001",
    "out_trade_no": "W202601010001",
    "status": "processing",
    "amount": 50000,
    "fee": 300,
    "fee_mode": "external",
    "hold_amount": 50300,
    "payee_amount": 50000,
    "payee_name": "张*",
    "payee_account_last4": "3445",
    "created_at": "2026-01-01T10:00:00+08:00"
  }
}

可能的错误码：IP_WHITELIST_REQUIRED、INVALID_PARAM、MERCHANT_NOT_FOUND、MERCHANT_FROZEN、PAYOUT_DISABLED、PRODUCT_NOT_ENABLED、DUPLICATE_OUT_TRADE_NO、SERVICE_UNAVAILABLE。

GET5.8 查询代付

GET https://api.example.com/v1/payouts/{order_no}
GET https://api.example.com/v1/payouts?out_trade_no={out_trade_no}

没有请求体，响应字段同 发起代付。不存在或不属于你返回 404 ORDER_NOT_FOUND。

6. 状态说明

代收订单 status

退款单 status

代付单 status

代付失败原因 failure_code

除上表外，上游通道返回失败时，failure_code 可能是上游给出的错误码，请以 failure_msg 为准。

7. 事件通知

7.1 格式

订单状态变化时，平台向订单的 notify_url 发送 HTTP POST。退款通知发到原订单的 notify_url。请求头：

请求体：

{
  "event_id": "01JGZ9A1B2C3D4E5F6G7H8J9K0",
  "event_type": "payin.paid",
  "created_at": "2026-01-01T00:03:21Z",
  "data": {
    "order_no": "P2026010100000001",
    "out_trade_no": "M202601010001",
    "status": "paid",
    "order_amount": 10000,
    "pay_amount": 10000,
    "merchant_fee": 60,
    "merchant_credit": 9940,
    "paid_at": "2026-01-01T08:03:21+08:00",
    "attach": "uid=1001"
  }
}

平台不跟随重定向，你的地址返回 3xx 按失败处理。通知地址只允许 http/https，端口只能是 80、443、8080、8443，不能解析到内网地址。平台发送通知的超时时间是 10 秒。

7.2 验签和处理

通知的签名方法和你给平台发请求时完全一样（3.1），你可以复用同一套签名代码：

• METHOD 是 POST。
• PATH 和 QUERY 取你的通知地址收到请求时的路径和查询参数（例如通知地址是 https://m.example.com/pay/notify?shop=1，则 PATH 为 /pay/notify，QUERY 为 shop=1）。
• BODY 是收到的请求体原始字节，不要先解析再序列化。

示例（密钥同上，X-Timestamp: 1767225602，X-Nonce: n0nce-0000000005）：请求体 {"event_id":"E1","event_type":"payin.paid","created_at":"2026-01-01T00:00:02Z","data":{"order_no":"P1","status":"paid"}}，待签名串：

POST
/pay/notify
shop=1
1767225602
n0nce-0000000005
fc2c16e95e3338fb0830456c947d7ff9d5919115b3e3d3b1816d64e02e0ac281

签名为 f759856d695aa15f2dbafe968be0972314fb84ea6a5eb400bce4573f2ef9523e。

收到通知后按下面顺序处理：

1. 检查 X-App-Id 等于你自己的 app_id。
2. 检查 X-Timestamp 与你服务器时间相差不超过 300 秒。
3. 按上面方法计算签名，和 X-Signature 比较（用常量时间比较函数）。不一致就拒绝（返回 4xx），不要处理数据。
4. 按 event_id 去重：把已处理的 event_id 记下来，重复收到时不再重复处理业务，但仍要返回 2xx。
5. 更新你自己的订单状态。金额以通知里的 data 为准，必要时再调用 查询接口 核对。
6. 返回 HTTP 2xx（响应内容任意，例如 success）。返回非 2xx、3xx 或超时，平台都会重试。

7.3 重试规则

通知失败（连接失败、超时、返回非 2xx）后按下面的间隔重试。第 1 次投递在事件产生后立即进行，之后每次失败等待对应的间隔再投递：

也就是一个事件最多投递 9 次。放弃之后平台不会再自动发送，请用 查询接口 兜底，也可以联系平台处理。

7.4 事件和 data

金额字段单位都是分。建议按 event_type 分支处理，对不认识的 event_type 返回 2xx 即可（避免平台持续重试）。test.ping 用于联调：验签通过并返回 2xx 即算成功。

7.5 出口 IP 白名单

如果你的服务器有防火墙或只接收白名单 IP 的请求，请放行下面这些平台发通知所用的出口 IP：

平台的通知来源 IP 在商户后台「对接资料」页面查看。平台换服务器时 IP 可能变化，以后台显示的为准。

注意这是平台访问你的出口 IP；你访问平台接口时使用的 IP 则要加到商户后台的 API 白名单里，两者方向不同。

8. 错误码

失败时响应为 {"code":"错误码","message":"中文说明","request_id":"..."}（INVALID_SIGNATURE 另带 data.sign_base）。HTTP 状态码和错误码一起判断。网络错误或超时不是业务错误，见 常见问题。

验签和通用错误

验签阶段的错误，响应没有签名头。

业务错误

代付被风控拒绝、余额不足、超过单日上限、没有可用通道不是 HTTP 错误，而是 HTTP 200 加 status: failed，原因见 代付失败原因。

9. SDK 下载

SDK 只依赖各语言标准库，封装了签名、请求、响应验签和通知验签，包内的 README 有下单、查询、处理通知的完整示例。

也可以登录商户后台，在「对接资料」页面下载。

10. 常见问题

签名不一致（INVALID_SIGNATURE）怎么排查？

响应的 data.sign_base 是平台根据你的请求算出的待签名串（不含密钥）。把它和你程序里的待签名串逐行对比（共 6 行：METHOD、PATH、QUERY、TIMESTAMP、NONCE、BODY 的 sha256），也可以把它粘贴到上面调试器的“平台返回的 sign_base”里自动对比。常见原因：

• 第 1 行方法没有大写，或第 2 行 PATH 带了域名、查询串，或漏了路径前缀。
• 第 3 行查询串没有排序，或编码规则不对（空格要用 +，~ 不编码，* 要编成 %2A）。
• 第 6 行 BODY 的 sha256 不同：签名用的字符串和实际发送的字节不是同一份（例如签名后又重新序列化、被框架改了格式、编码不是 UTF-8、GET 请求却带了请求体）。
• sign_base 完全一致但签名仍然不对：密钥错误，或者密钥被当成十六进制解码了（应按文本使用），或者结果用了大写。
• 时间戳或 Nonce：签名用的值和请求头里的值不是同一个。

报 TIMESTAMP_EXPIRED 怎么办？

说明你的服务器时间和平台相差超过 300 秒。用 NTP 校准时间；每次请求都取当前时间生成时间戳并重新签名；用的是秒，不是毫秒。

报 NONCE_REUSED 怎么办？

X-Nonce 在 10 分钟内重复了。每次请求，包括超时后的重试，都要生成新的随机 Nonce（建议用安全随机数生成 32 位十六进制）。不要用固定值，也不要用只精确到秒的时间戳当 Nonce。

为什么代付必须设置 IP 白名单？

代付是出款操作，为了避免密钥泄露后被人直接转走资金，平台要求代付所用的密钥必须在商户后台设置 IP 白名单，并且只接受白名单内 IP 的请求。没设置时返回 403 IP_WHITELIST_REQUIRED；IP 不在白名单内返回 403 IP_NOT_ALLOWED。

网络超时了，要不要换单号重新下单？

不要。超时只说明你没收到响应，不代表平台没有收到请求。正确做法：

• 用同一个商户单号调用查询接口。查到了就用查询结果；查不到（404）说明平台没有收到，再用同一个单号和相同的参数重新提交，是安全的，不会重复下单。
• 代付、退款同理：status 为 unknown 或请求超时时，不要换单号重发，以通知或查询结果为准。
• 换新单号重发可能造成用户重复付款或重复出款。

通知收不到怎么办？

检查：下单时是否填了 notify_url；地址是否是公网可访问的 http/https，端口是否为 80、443、8080、8443；你的防火墙是否放行了 平台出口 IP；服务是否在 10 秒内返回了 2xx；是否返回了 3xx（平台不跟随重定向）。无论如何，都要用 查询接口 兜底。

重复收到同一个通知怎么办？

正常现象（重试、你的响应超时）。按 event_id 去重，已处理的直接返回 2xx。

pay_amount 和 order_amount 为什么不一样？

有立减活动时，用户实付金额 pay_amount 会小于订单金额 order_amount。收款以 pay_amount 为准。