商户对接文档

对接必懂：第 4 步 notify POST = 入账发货；第 5 步 return GET = 用户看成功页。详细说明见完整 Markdown 文档。

1. 准备工作

项目	说明
`pid`	商户号，后台「商户账号」列表第一列
API 密钥	创建商户时生成，用于签名与验签 notify
`channel`	支付通道码；建议在商户中绑定默认通道
网关	本站根地址，如 `http://jd.xiaoil.com`

安全：密钥仅放服务端；notify_url 必须为可公网访问的 HTTPS 地址。

2. 签名算法（MD5）

参与签名参数：除 sign、sign_type 外，且值非空。
按 key ASCII 升序，拼接 key=value&...（不 URL 编码）。
末尾直接追加 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. 接口一览

能力	方法	路径
创建订单	POST	`/api/epay/submit`、`/api/channel/submit`
查询订单	GET/POST	`/api/epay/query`、`/api/channel/query`
页面跳转	GET	`/pay/{通道码}?pid&…`
收银台	GET	`/pay/cashier?trade_no=`

请求体支持 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

请求参数

参数	必填	说明
pid	是	商户号（可用 mch_id）
out_trade_no	是	商户订单号，不可重复
money	是	金额，如 1.00
sign	是	MD5 签名
name	否	商品名称
channel	条件	通道码；已绑定默认通道可省略
notify_url	强烈建议	POST 异步通知 → 入账用这个
return_url	需回跳时必传	GET 浏览器跳转 → 只展示，不入账
type	否	建议 jd

成功响应

{
  "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"
}

建议：将用户跳转至 payurl 使用自带收银台；或自行用 qrcode 生成二维码并轮询查单。

4A. 完整对接流程

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

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

4B. return_url 与 notify_url（重要）

	notify_url	return_url
方式	POST 服务端	GET 浏览器跳转
用途	验签入账、发货	用户支付成功页
是否必传	强烈建议	需回跳商户站时必传

勿只传 notify：无 return_url 时收银台会 GET 打开 notify 地址，多数接口只收 POST 会失败。请同时配置两者。

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

5. 查询订单

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

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

trade_status	含义
WAIT_BUYER_PAY	待支付
TRADE_SUCCESS	支付成功
TRADE_FAILED	失败/超时
TRADE_REFUND	已退款

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

订单默认 countdown_seconds=900（15 分钟，以通道配置为准），超时 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. 常见错误

msg	说明
签名错误	排序、空值或密钥错误
商户订单号重复	out_trade_no 已存在
未指定通道…	传 channel 或绑定默认通道

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', 'type' => 'jd',
  'out_trade_no' => 'ORDER' . time(),
  'money' => '1.00', 'name' => '测试',
  'notify_url' => 'https://你的域名/api/pay/notify',
  'return_url' => 'https://你的域名/pay/success',
  'channel' => 'your_channel', '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 密钥
已配置通道并绑定商户
服务端实现签名与 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=京东直链+自行查单。