演示文档，示例数据。正式环境参数与返回以签约后配置为准。
去沙箱验证 →接口文档中心
接口文档
按章节说明鉴权、参数与返回结构。建议先在沙箱完成一次完整调用，再按文档接入正式环境。
接入准备
确认环境、凭证与回调地址后即可开始联调。
接入前先在控制台完成商户注册，取得商户号、API Key 与签名密钥。签名密钥只用于服务端计算签名，不得下发到浏览器或客户端。
建议先在沙箱环境完成参数与签名验证，确认返回结构符合预期后，再切换到正式环境配置。
- 商户号：标识请求来源的商户唯一编号
- API Key：请求身份标识，可公开出现在请求参数中
- 签名密钥：仅用于服务端签名计算，禁止写入前端代码
- 回调地址：接收支付结果通知的 HTTPS 地址
鉴权与签名
所有请求按字段升序拼接后计算签名，服务端校验一致性。
将除 sign 外的非空参数按参数名 ASCII 升序拼接为 key=value&key=value 形式，末尾追加密钥后做 SHA-256，结果转为小写十六进制即为签名。
服务端会重新计算签名并比对，签名不一致时返回 SIGN_ERROR，需检查参数是否被改写、是否漏传字段或密钥是否使用正确。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_id | string | 是 | 商户号，控制台凭证页可查看 |
| nonce_str | string | 是 | 随机字符串，建议 32 位以内 |
| timestamp | string | 是 | 秒级时间戳，与服务端偏差不超过 300 秒 |
| sign | string | 是 | 按签名规则计算的结果 |
params = { "app_id": "M20260101001", "amount": "100", "out_trade_no": "T20260101001" }
raw = "amount=100&app_id=M20260101001&out_trade_no=T20260101001"
sign = sha256(raw + "&key=" + secret_key).hex().lower()公共参数
公共参数在每个接口中都需要携带。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| app_id | string | 是 | 商户号 |
| nonce_str | string | 是 | 随机字符串 |
| timestamp | string | 是 | 秒级时间戳 |
| sign | string | 是 | 签名结果 |
| env | string | 否 | sandbox / production，默认 production |
错误码
返回码用于判断结果，错误说明用于定位问题。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| SUCCESS | — | — | 请求处理成功 |
| PARAM_ERROR | — | — | 缺少必填参数或格式不正确 |
| SIGN_ERROR | — | — | 签名校验失败 |
| ORDER_NOT_EXIST | — | — | 订单号不存在 |
| ORDER_DUPLICATE | — | — | 商户订单号重复提交 |
| CHANNEL_ERROR | — | — | 通道处理异常，可稍后重试 |
下单接口
创建一笔收款订单，返回支付参数。
请求地址：POST /v1/order/create。金额单位为分，订单号由商户生成并保证唯一。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| out_trade_no | string | 是 | 商户订单号，长度不超过 32 位 |
| amount | int | 是 | 订单金额，单位为分 |
| channel | string | 是 | wechat / alipay / bank / unionpay |
| subject | string | 是 | 订单标题，用于展示 |
| notify_url | string | 否 | 结果通知地址，不传则使用控制台配置 |
POST /v1/order/create
Content-Type: application/x-www-form-urlencoded
app_id=M20260101001&out_trade_no=T20260101001&amount=10000&channel=alipay&subject=会员续费&nonce_str=8f3c1a×tamp=1767225600&sign=...{
"code": "SUCCESS",
"message": "ok",
"data": {
"order_no": "P20260101000001",
"out_trade_no": "T20260101001",
"amount": 10000,
"status": "CREATED",
"pay_params": { "qr_code": "https://example.invalid/qr/P20260101000001" }
}
}查询接口
按商户订单号或平台订单号查询当前状态。
请求地址：GET /v1/order/query。回调未收到时可用查询接口做兜底确认。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| out_trade_no | string | 否 | 商户订单号，与 order_no 二选一 |
| order_no | string | 否 | 平台订单号，与 out_trade_no 二选一 |
{
"code": "SUCCESS",
"data": {
"order_no": "P20260101000001",
"status": "PAID",
"paid_at": "2026-01-01 10:00:00",
"amount": 10000
}
}退款接口
对已支付订单发起退款，支持部分退款。
请求地址：POST /v1/refund/create。同一订单多次退款时累计金额不得超过原订单金额。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| out_trade_no | string | 是 | 原商户订单号 |
| out_refund_no | string | 是 | 退款单号，商户内唯一 |
| refund_amount | int | 是 | 退款金额，单位为分 |
| reason | string | 否 | 退款原因说明 |
{
"code": "SUCCESS",
"data": {
"refund_no": "R20260101000001",
"status": "PROCESSING",
"refund_amount": 5000
}
}回调通知
支付结果以回调通知为准，需要验签与幂等处理。
支付完成后服务端向回调地址发送 POST 请求，参数结构与下单返回一致。商户需校验签名、判断订单状态，并在处理后返回 SUCCESS 字符串。
未收到成功响应时会按退避策略重复通知。请按订单号做幂等处理，避免重复发货或重复记账。
{
"order_no": "P20260101000001",
"out_trade_no": "T20260101001",
"status": "PAID",
"amount": 10000,
"paid_at": "2026-01-01 10:00:00",
"sign": "..."
}常见对接问题
联调阶段最常见的几类问题与排查顺序。
- 签名不通过：确认参数按升序拼接、未包含 sign 字段、空值未参与计算
- 订单重复：商户订单号需保证唯一，重试时复用原订单号前先查询状态
- 回调未收到：确认地址为 HTTPS 且公网可达，处理逻辑需在超时内返回 SUCCESS
- 金额不一致：接口金额单位为分，展示层转换时注意不要二次乘除