商户对接文档

1. 准备工作

1B. channel 与 type（易错）

1C. 轮询组

多个通道可加入同一组。对接时 channel=组编码，平台自动轮询组内启用通道。页面跳转同样支持：/pay/{组编码}?…

2. 签名算法（MD5）

1. 参与签名参数：除 sign、sign_type 外，且值非空。
2. 按 key ASCII 升序，拼接 key=value&...（不 URL 编码）。
3. 末尾直接追加 API 密钥，MD5 小写 32 位 → sign。

示例待签串：

money=1.00&name=测试商品&notify_url=https://merchant.example.com/notify&out_trade_no=20260101120000&pid=1001&type=jd{您的API密钥}

3. 接口一览

请求体支持 application/x-www-form-urlencoded、multipart/form-data、application/json。

响应：{"code":1,"msg":"success",...} 成功；code:-1 失败。

4. 创建订单

POST http://jd.xiaoil.com/api/epay/submit

请求参数

成功响应

{
  "code": 1,
  "msg": "success",
  "trade_no": "JD202601011234567890",
  "out_trade_no": "20260101120000",
  "payurl": "http://jd.xiaoil.com/pay/cashier?trade_no=JD...",
  "qrcode": "https://wepay.jd.com/...",
  "money": "1.00",
  "pay_amount": "1.00",
  "countdown_seconds": 900,
  "expires_at": "2026-01-01T12:15:00Z"
}

4A. 三种对接方式

4B. 完整对接流程

1. 商户服务端 POST /api/epay/submit，获得 payurl、trade_no
2. 引导用户打开 payurl 收银台完成支付
3. 平台 POST notify_url → 商户验签、幂等入账，响应 success
4. 收银台检测到成功 → 浏览器 GET 跳转 return_url（带签名参数）

入账以 notify 为准；return 仅用于用户回跳展示。

4C. return_url 与 notify_url（重要）

跳转优先级：return_url →（无则）notify_url →（均无）/pay/success

5. 查询订单

GET/POST http://jd.xiaoil.com/api/epay/query

参数：pid、sign，以及 out_trade_no 或 trade_no 二选一。

6. 页面跳转下单

GET http://jd.xiaoil.com/pay/{通道码}?pid=&out_trade_no=&money=&name=&sign=&sign_type=MD5

验签通过后创建订单并跳转收银台，适合浏览器直接打开。

7. 收银台

• GET /pay/cashier?trade_no= — 展示页，每 3 秒轮询，成功自动跳转 redirect_url
• GET /api/cashier/order?trade_no= — 订单详情、二维码、倒计时；已支付时含 redirect_url
• GET /api/cashier/poll?trade_no= — 轮询；成功返回 redirect_url

订单倒计时：金融充值 900 秒、保证金 5400 秒、安徽农信 1800 秒（以通道配置为准），超时 TRADE_FAILED。

8. 异步通知与同步跳转

平台 POST 至 notify_url（application/x-www-form-urlencoded）。字段：pid, trade_no, out_trade_no, type, name, money, pay_amount, trade_status, sign。验签后响应正文含 success（HTTP 200），失败重试约 5 次。

return_url GET 参数（支付成功回跳）

与 notify 相同字段，trade_status=TRADE_SUCCESS，附在 Query 上，用商户密钥验签。示例：

https://merchant.example.com/ok?pid=1001&trade_no=JD...&out_trade_no=...&money=1.00&trade_status=TRADE_SUCCESS&sign=...

入账仍以 notify 为准，return 不可单独作为发货依据。

9. 常见错误

10. 代码示例（PHP）

function epaySign($params, $key) {
  unset($params['sign'], $params['sign_type']);
  $params = array_filter($params, fn($v) => $v !== '' && $v !== null);
  ksort($params);
  $str = '';
  foreach ($params as $k => $v) {
    $str .= ($str === '' ? '' : '&') . $k . '=' . $v;
  }
  return md5($str . $key);
}
$params = [
  'pid' => '1001',
  'channel' => 'ahpay',  // 通道码或轮询组编码
  'out_trade_no' => 'ORDER' . time(),
  'money' => '1.00', 'name' => '测试',
  'notify_url' => 'https://你的域名/api/pay/notify',
  'return_url' => 'https://你的域名/pay/success',
  'client_ip' => $_SERVER['REMOTE_ADDR'] ?? '',
  'sign_type' => 'MD5',
];
$params['sign'] = epaySign($params, $apiKey);
// POST http://jd.xiaoil.com/api/epay/submit → 跳转 $result['payurl']

notify 入账（PHP）

if (!verifySign($_POST, $apiKey)) exit('sign error');
if ($_POST['trade_status'] === 'TRADE_SUCCESS') { /* 幂等更新订单 */ }
echo 'success';

11. 对接检查清单

• 已创建商户并保存 pid、API 密钥
• 网关使用 https://
• 轮询组传 channel=组编码，不写进 type
• 已配置通道/轮询组并绑定商户
• 服务端实现签名与 notify 验签
• notify 可 POST 访问且返回 success
• 已配置 return_url（需用户回跳时必做）
• out_trade_no 幂等、生产 HTTPS

12. 常见问题

只传 notify 不传 return？ 用户支付后可能 GET 打开 notify 地址导致异常，请传 return_url。

notify 和 return 哪个先到？ 不固定；入账只认 notify。

用户关页面还会 notify 吗？ 会，支付成功即 POST。

payurl 和 qrcode？ payurl=本站收银台（自动回跳）；qrcode=支付直链+自行查单。

轮询组怎么传？ channel=组编码 或 /pay/组编码?…，不要写在 type 里。

type 可以不传吗？ 可以，不参与选通道。