把这些地址配进你自己的服务器。换域名后重新打开本页,地址会跟着变。
想先跑通一笔,打开 对接演练。演练页里的接口地址同样是当前域名。
| 你看到的 | 什么时候用 | 字段名 |
|---|---|---|
| 商户号 | 只用来登录商户后台。接口不收这个号。 | 后台登录框,不参与签名 |
| 对接账号 | 每次请求都要带。后台「对接信息」里的对接账号。 | api_key |
| 对接密钥 | 只放在你自己的服务器上算签名,不要写进网页、不要传给顾客。 | 签名串末尾的 secret,参数名不要叫 secret |
| 你自己的订单号 | 你系统里的单号。同一商户不能重复。 | 下单时叫 order_no。查单、通知里叫 merchant_order_no |
| 平台订单号 | 下单成功后返回,形如 P 开头。退款必须用它。查单也可以用它。 | 返回、查单、通知里都叫 order_no |
order_no 是你的单号。下单返回里的 data.order_no 是平台单号。两个都要存下来。POST。正文是表单,Content-Type: application/x-www-form-urlencoded,编码 UTF-8。不要发 JSON 正文,JSON 不会被读取。100.00。不要传分。api_key、timestamp(当前 Unix 秒)、sign。时间和服务端相差超过 300 秒会拒绝,提示「请求已过期」。code 为 0。业务失败同样是 HTTP 200,code 为 1,msg 是原因,data 为 null。跨站浏览器请求会被拒绝,HTTP 403,服务器对服务器调用没有这个问题。{ "code": 0, "msg": "success", "data": { } }
{ "code": 1, "msg": "签名错误", "data": null }
sign。空字符串不参与。数值 0 要参与。参数名=值&参数名=值,参数之间一个 &,末尾再加 &secret=对接密钥。sign。密钥本身不要作为参数提交。下面这组参数的签名是固定的,可以对一下你自己的代码。对接密钥是 sk_demo。
function build_sign(array $params, $secret) {
unset($params['sign']);
ksort($params);
$pairs = [];
foreach ($params as $k => $v) {
if ($v === '' || $v === null) continue;
$pairs[] = $k . '=' . $v;
}
return md5(implode('&', $pairs) . '&secret=' . $secret);
}
用同样的算法,密钥仍是对接密钥。比较时用恒定时间比较,不要自己拼完再 == 完就发货。金额必须等于下单返回的 data.amount,单号必须是你发出去的那一笔。
POST
| 参数 | 必填 | 说明 |
|---|---|---|
| api_key | 是 | 对接账号 |
| timestamp | 是 | 当前 Unix 时间,秒 |
| sign | 是 | 按上一节计算 |
| order_no | 是 | 你自己的订单号。待支付时用同一单号再请求,会返回原来的付款信息,不会另开一笔。已支付、已关闭后再用同一单号,返回「订单号重复」 |
| amount | 是 | 你希望收取的金额,例如 100.00。顾客实际要付的金额看返回里的 amount,两者可能不同 |
| pay_method | 是 | 支付方式编码,见下表。必须是运营已经给这个商户开通的方式 |
| notify_url | 是 | 付款成功后通知你的服务器。只支持 http 或 https,不能是内网地址。若后台填了回调域名,主机名必须落在白名单里 |
| return_url | 否 | 顾客在收银台看到「支付成功」约 2 秒后,浏览器跳到这里。服务器发货不要依赖这次跳转 |
| subject | 否 | 商品名称,默认「商品支付」 |
| currency | 否 | 币种,不传默认 CNY |
| ip | 否 | 付款人 IP。不传则用你这台服务器的出口 IP,风控会按这个 IP 判断 |
| 编码 | 顾客侧表现 |
|---|---|
| alipay_scan | 支付宝扫码。通常返回一段二维码内容 |
| wechat_scan | 微信扫码。通常返回一段二维码内容 |
| alipay_h5 | 手机浏览器里拉起支付宝。通常返回 http 开头的跳转地址 |
| wechat_h5 | 手机浏览器里拉起微信。通常返回 http 开头的跳转地址 |
运营若在后台另建了支付方式,编码以后台为准,算法不变。
| 字段 | 你要拿它做什么 |
|---|---|
| order_no | 平台订单号。存下来。退款、用平台单号查单都用它 |
| amount | 顾客实际要付的金额。页面上显示这个。通知里的金额也是这个。通道开了金额浮动时,它会和你传入的金额差零点几元 |
| request_amount | 你传入的金额,原样返回,便于你对账 |
| float_amount | 浮动差额。实际金额 = 你传入的金额 + 这个差额 |
| checkout_url | 本系统的收银台页面。大多数商户把顾客送到这里即可 |
| pay_url | 上游给出的付款内容。见下一节,不要无脑当图片地址 |
| app_scheme | 拉起 App 的链接,可能是空字符串。有值时做成按钮,例如「打开支付宝」 |
{
"code": 0,
"msg": "success",
"data": {
"order_no": "P202611190001",
"pay_url": "https://上游收银台或一段二维码原文",
"checkout_url": "当前域名/checkout.php?order_no=P202611190001&token=...",
"app_scheme": "",
"amount": "100.17",
"request_amount": "100.00",
"float_amount": "0.17"
}
}
二选一。不要两种各做一半。
这是默认做法。浏览器跳转到返回的 checkout_url,或给一个按钮「去支付」,链接就是这个地址。
pay_url 以 http 或 https 开头时,显示「去支付」按钮;否则把 pay_url 画成二维码。app_scheme 时,收银台再显示「打开支付宝 / 微信」。return_url,约 2 秒跳回你的页面。你不想用收银台时,按 pay_url 的内容决定,不要一律做成二维码,也不要一律跳转。
| pay_url 长什么样 | 你该做什么 |
|---|---|
以 http:// 或 https:// 开头 | 这是跳转地址。手机网站用 location.href 打开,或放一个「去支付」按钮。这是拉起支付,不是二维码图片地址 |
| 其他内容(微信/支付宝协议、一串码) | 把这段原文生成二维码给顾客扫。二维码的内容就是 pay_url 本身,不要再套一层网址 |
| app_scheme 不是空 | 在手机页面上加按钮,点击打开这个链接,用来拉起支付宝或微信 |
trade_status = PAID。顾客浏览器跳回 return_url 只能当展示,不能当付款凭证。POST 。签名参数和下单相同。待支付超过 60 秒时,查单会向上游同步一次状态。
| 参数 | 必填 | 说明 |
|---|---|---|
| api_key / timestamp / sign | 是 | 同下单。这次没提交的业务字段不要放进签名 |
| order_no | 二选一 | 平台订单号,即下单返回的 data.order_no。两个都传时以这个为准 |
| merchant_order_no | 二选一 | 你自己的订单号,即下单时传入的 order_no |
| 字段 | 说明 |
|---|---|
| order_no | 平台订单号 |
| merchant_order_no | 你的订单号 |
| channel_order_no | 上游单号,可能为空 |
| amount | 实际支付金额 |
| request_amount | 你下单时传入的金额 |
| float_amount | 浮动差额 |
| currency | 币种 |
| status | 数字。0 待支付,1 已支付,2 支付失败,3 已退款,4 已关闭 |
| trade_status | WAIT_PAY / PAID / FAIL / REFUNDED / CLOSED。发货判断用这个,值为 PAID |
| status_text | 中文状态,给页面展示 |
| pay_method | 下单时的支付方式 |
| pay_url / checkout_url / app_scheme | 与下单返回相同,未支付时仍可继续用 |
| paid_at | 支付时间,未支付为空 |
| created_at | 创建时间 |
{
"code": 0,
"msg": "success",
"data": {
"order_no": "P202611190001",
"merchant_order_no": "SHOP20261119001",
"amount": "100.17",
"request_amount": "100.00",
"float_amount": "0.17",
"currency": "CNY",
"status": 1,
"trade_status": "PAID",
"status_text": "已支付",
"pay_method": "alipay_scan",
"paid_at": "2026-11-19 02:00:00",
"created_at": "2026-11-19 01:58:00"
}
}
POST 。只接受平台订单号。订单必须是已支付。退款没有异步通知,以这次返回为准。
| 参数 | 必填 | 说明 |
|---|---|---|
| api_key / timestamp / sign | 是 | 同下单 |
| order_no | 是 | 平台订单号,不是你自己的订单号 |
| refund_amount | 是 | 本次退款金额,元,两位小数。不能超过剩余可退金额。部分退款后订单仍是已支付,全部退完才变为已退款 |
{
"code": 0,
"msg": "success",
"data": { "refund_no": "R202611190001", "refund_amount": "100.17" }
}
余额不足以退回已结算金额时,会直接失败,上游不会先退。常见失败:订单不存在、订单状态不允许退款、退款金额超过可退金额、商户余额不足。
顾客付款成功后,本系统向你下单时填的 notify_url 发 POST,正文同样是表单,不是 JSON。
| 字段 | 说明 |
|---|---|
| order_no | 平台订单号 |
| merchant_order_no | 你的订单号。用它找到你自己的订单 |
| amount | 实际支付金额,应等于下单返回的 data.amount |
| currency | 币种 |
| status | 字符串,不是数字。"1" 表示已支付。程序里不要用数字 1 去做全等比较 |
| trade_status | PAID 才发货。其余为 WAIT_PAY、FAIL、REFUNDED、CLOSED |
| pay_method | 支付方式 |
| paid_at | 支付时间。为空时不参与签名 |
| timestamp | 本次通知发出的时间,秒。参与签名 |
| sign | 用对接密钥按同一算法计算 |
处理要求:先验签,再核对 merchant_order_no 和 amount,并且同一笔只发货一次。全部成功后,响应正文只能是六个小写字母 success,不要带 HTML、空格或 JSON。不是这六个字母,会按 0 秒、60 秒、5 分钟、30 分钟、1 小时重试,最多 5 次。
amount=100.17¤cy=CNY&merchant_order_no=SHOP20261119001&order_no=P202611190001&paid_at=2026-11-19 02:00:00&pay_method=alipay_scan&status=1×tamp=1730000100&trade_status=PAID&secret=对接密钥
上面是通知验签时要做 MD5 的原串。字段按名字排序,空的 paid_at 整段去掉。
可选。地址是 ,把商户号放在 query 里:?m=商户号&a=pay,查单把 a 换成 query,退款换成 refund。这种调用不要再传 api_key,签名里也不要放 api_key。其余字段与上面三个接口相同。