返回首页

接入文档

下面的地址按你现在打开的这个站点自动生成。商户号只用来登录后台,调接口用对接账号和对接密钥。

当前站点地址

把这些地址配进你自己的服务器。换域名后重新打开本页,地址会跟着变。

下单
查单
退款
演练

想先跑通一笔,打开 对接演练。演练页里的接口地址同样是当前域名。

先分清三个号码

你看到的什么时候用字段名
商户号只用来登录商户后台。接口不收这个号。后台登录框,不参与签名
对接账号每次请求都要带。后台「对接信息」里的对接账号。api_key
对接密钥只放在你自己的服务器上算签名,不要写进网页、不要传给顾客。签名串末尾的 secret,参数名不要叫 secret
你自己的订单号你系统里的单号。同一商户不能重复。下单时叫 order_no。查单、通知里叫 merchant_order_no
平台订单号下单成功后返回,形如 P 开头。退款必须用它。查单也可以用它。返回、查单、通知里都叫 order_no
下单请求里的 order_no 是你的单号。下单返回里的 data.order_no 是平台单号。两个都要存下来。

请求约定

{ "code": 0, "msg": "success", "data": { } }
{ "code": 1, "msg": "签名错误", "data": null }

签名

  1. 拿出这次请求的全部参数,去掉 sign。空字符串不参与。数值 0 要参与。
  2. 按参数名的 ASCII 从小到大排序。
  3. 拼成 参数名=值&参数名=值,参数之间一个 &,末尾再加 &secret=对接密钥。
  4. 对整串做 MD5,32 位小写。这就是 sign。密钥本身不要作为参数提交。

下面这组参数的签名是固定的,可以对一下你自己的代码。对接密钥是 sk_demo。


      

PHP

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 判断

pay_method

编码顾客侧表现
alipay_scan支付宝扫码。通常返回一段二维码内容
wechat_scan微信扫码。通常返回一段二维码内容
alipay_h5手机浏览器里拉起支付宝。通常返回 http 开头的跳转地址
wechat_h5手机浏览器里拉起微信。通常返回 http 开头的跳转地址

运营若在后台另建了支付方式,编码以后台为准,算法不变。

成功时 data 里有这些字段

字段你要拿它做什么
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 的内容决定,不要一律做成二维码,也不要一律跳转。

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

成功时 data

字段说明
order_no平台订单号
merchant_order_no你的订单号
channel_order_no上游单号,可能为空
amount实际支付金额
request_amount你下单时传入的金额
float_amount浮动差额
currency币种
status数字。0 待支付,1 已支付,2 支付失败,3 已退款,4 已关闭
trade_statusWAIT_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_statusPAID 才发货。其余为 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&currency=CNY&merchant_order_no=SHOP20261119001&order_no=P202611190001&paid_at=2026-11-19 02:00:00&pay_method=alipay_scan&status=1&timestamp=1730000100&trade_status=PAID&secret=对接密钥

上面是通知验签时要做 MD5 的原串。字段按名字排序,空的 paid_at 整段去掉。

独立网关

可选。地址是 ,把商户号放在 query 里:?m=商户号&a=pay,查单把 a 换成 query,退款换成 refund。这种调用不要再传 api_key,签名里也不要放 api_key。其余字段与上面三个接口相同。