开发文档

# 接入指南

# JianPay 简付 AI 接入总览

网关地址：
- 主网关：https://jpay.hzjianban.com
- 备用网关（支持 IPv6）：https://api.jian-pay.com

调用时任选一个网关，并在网关地址后拼接下面的接口路径。

接入目标：
- 在商户自己的服务端完成下单、签名、支付回调验签、查单补偿和退款处理。
- 前端只负责打开 payUrl、展示 payQrcodeUrl，或使用 API 下单返回的 payInfo / qrCode / payActionUrl 拉起支付。
- 不要把商户 KEY 写到浏览器、H5、小程序或 App。

前置准备：
- 在 API安全 页面拿到商户号 clientNo 和商户 KEY；如果需要回调，再准备自己的 notifyUrl。
- 商户号：clientNo
- 商户密钥：KEY
- 支付通知回调地址：notifyUrl，非必填；填写时必须是自己的服务端接口。

接入场景：
- 扫码支付：优先使用收银台下单，展示返回的 payQrcodeUrl，用户使用微信或支付宝扫码。
- JSAPI 支付：有营业执照且已有自建支付页时，使用 API 下单获取 payInfo。
- H5 支付：仅个体工商户和企业主体支持，使用收银台下单并跳转返回的 payUrl。
- 有营业执照且已有自建支付页：使用 API 下单，按支付场景选择 jsapi 或 native，并结合 notifyUrl 和主动查单确认结果。
- 小微个人主体：直接使用收银台下单即可，不建议接入 API 下单。

标准接入流程：
1. 服务端按 MD5 规则签名后发起下单。
2. 收银台方案使用 payUrl 或 payQrcodeUrl。
3. API 方案使用 qrCode、payActionUrl 或 payInfo。
4. 配置 notifyUrl 时，以支付通知回调为准更新订单。
5. 未配置 notifyUrl 或回调未及时到达时，主动调用查单接口。

接口路径：
- 收银台下单：POST /open/payment/pay/create
- API 下单：POST /open/payment/pay/api-create
- 查询订单：POST /open/payment/pay/info
- 申请退款：POST /open/payment/refund/create
- 退款查询：POST /open/payment/refund/query

---

# 收银台下单接口

接口地址：
POST /open/payment/pay/create

适用场景：
- 扫码支付展示 payQrcodeUrl。
- H5 支付仅个体工商户和企业主体支持，使用时跳转 payUrl。
- 不想自建支付页时优先使用。

请求参数：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| clientNo | string | 是 | 商户号 |
| amount | number | 是 | 订单金额，单位分 |
| orderNo | string | 是 | 商户订单号，同一商户号下唯一 |
| goodsName | string | 是 | 商品名称 |
| payMethod | string | 是 | 支付方式，wx 或 alipay |
| notifyUrl | string | 否 | 商户自己的服务端支付通知地址 |
| returnUrl | string | 否 | 支付完成后的页面跳转地址 |
| param | string | 否 | 附加参数，通知时原样返回 |
| timestamp | string | 否 | 请求时间戳 |
| sign_type | string | 是 | 固定 MD5 |
| sign | string | 是 | MD5 签名结果，小写 |

响应字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| code | number | 1000 表示接口调用成功 |
| message | string | 返回消息 |
| data.orderId | string | 简付平台订单号 |
| data.clientNo | string | 当前商户号 |
| data.merchantOrderNo | string | 商户订单号 |
| data.amount | number | 订单金额，单位分 |
| data.status | number | 订单状态：0 待发起、1 处理中、2 支付成功、3 支付失败、4 已关闭 |
| data.payUrl | string | 收银台地址 |
| data.payQrcodeUrl | string | 收银台二维码图片地址 |

请求示例：
```http
POST /open/payment/pay/create
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "amount": 100,
  "orderNo": "P202607080001",
  "goodsName": "测试商品",
  "payMethod": "wx",
  "notifyUrl": "https://example.com/pay/notify",
  "returnUrl": "https://example.com/pay/result",
  "param": "user_id=1001",
  "timestamp": "1783500000",
  "sign_type": "MD5",
  "sign": "md5签名"
}
```

返回示例：
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "orderId": "PAY202607080001000001",
    "clientNo": "JP26070612345678",
    "merchantOrderNo": "P202607080001",
    "amount": 100,
    "status": 1,
    "payUrl": "https://jpay.hzjianban.com/#/pay?orderId=PAY202607080001000001",
    "payQrcodeUrl": "https://quickchart.io/qr?size=300&text=https%3A%2F%2Fjpay.hzjianban.com%2F%23%2Fpay%3ForderId%3DPAY202607080001000001"
  }
}
```

---

# API 下单接口

接口地址：
POST /open/payment/pay/api-create

适用场景：
- 已有自己的支付页。
- 需要自己控制微信、支付宝拉起方式。
- 建议仅有营业执照的个体工商户或企业主体使用。
- 小微主体请优先使用收银台下单。
- JSAPI 场景需要按通道要求传 methodExpand。

请求参数：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| clientNo | string | 是 | 商户号 |
| amount | number | 是 | 订单金额，单位分 |
| orderNo | string | 是 | 商户订单号，同一商户号下唯一 |
| goodsName | string | 是 | 商品名称 |
| payMethod | string | 是 | 支付方式，wx 或 alipay |
| payType | string | 是 | 支付类型，jsapi 或 native |
| methodExpand | object | 条件必填 | 支付扩展参数，例如微信 JSAPI 的 sub_appid、sub_openid |
| notifyUrl | string | 否 | 商户自己的服务端支付通知地址 |
| returnUrl | string | 否 | 支付完成后的页面跳转地址 |
| param | string | 否 | 附加参数，通知时原样返回 |
| timestamp | string | 否 | 请求时间戳 |
| sign_type | string | 是 | 固定 MD5 |
| sign | string | 是 | MD5 签名结果，小写 |

响应字段：
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| data.orderId | string | 简付平台订单号 |
| data.qrCode | string | 扫码支付二维码内容链接 |
| data.payActionUrl | string | 可直接跳转的支付动作地址 |
| data.payInfo | object | JSAPI 场景的拉起支付参数 |

请求示例：
```http
POST /open/payment/pay/api-create
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "amount": 100,
  "orderNo": "P202607080002",
  "goodsName": "测试商品",
  "payMethod": "wx",
  "payType": "jsapi",
  "methodExpand": {
    "sub_appid": "wx807ca1e2f99e3039",
    "sub_openid": "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o"
  },
  "notifyUrl": "https://example.com/pay/notify",
  "returnUrl": "https://example.com/pay/result",
  "param": "user_id=1001",
  "timestamp": "1783500000",
  "sign_type": "MD5",
  "sign": "md5签名"
}
```

返回示例：
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "orderId": "PAY202607080001000002",
    "clientNo": "JP26070612345678",
    "merchantOrderNo": "P202607080002",
    "amount": 100,
    "status": 1,
    "payMethod": "wx",
    "payType": "jsapi",
    "qrCode": "",
    "payActionUrl": "",
    "payInfo": {
      "appId": "wx807ca1e2f99e3039",
      "timeStamp": "1783500000",
      "nonceStr": "a8f3k2m9",
      "package": "prepay_id=wx...",
      "signType": "RSA",
      "paySign": "..."
    }
  }
}
```

---

# 查询订单接口

接口地址：
POST /open/payment/pay/info

用途：
- notifyUrl 未配置时，必须主动查单确认支付结果。
- notifyUrl 已配置但回调暂未到达时，用查单做补偿。
- 不要依赖前端跳转页面判断支付成功。

请求参数：
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| clientNo | string | 是 | 商户号 |
| orderId | string | 二选一 | 简付平台订单号 |
| merchantOrderNo | string | 二选一 | 商户下单时传入的 orderNo；与 orderId 至少填写一个 |
| timestamp | string | 否 | 请求时间戳 |
| sign_type | string | 是 | 固定 MD5 |
| sign | string | 是 | MD5 签名结果，小写 |

请求示例：
```http
POST /open/payment/pay/info
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "orderId": "PAY202607080001000001",
  "timestamp": "1783500001",
  "sign_type": "MD5",
  "sign": "md5签名"
}
```

按商户订单号查询：
```http
POST /open/payment/pay/info
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "merchantOrderNo": "P202607080001",
  "timestamp": "1783500001",
  "sign_type": "MD5",
  "sign": "md5签名"
}
```

返回示例：
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "orderId": "PAY202607080001000001",
    "clientNo": "JP26070612345678",
    "merchantOrderNo": "P202607080001",
    "amount": 100,
    "status": 2,
    "goodsName": "测试商品",
    "payMethod": "wx",
    "payType": "jsapi",
    "param": "user_id=1001",
    "paidAt": "2026-07-08 12:30:00"
  }
}
```

---

# 退款接口

申请退款：
POST /open/payment/refund/create

退款查询：
POST /open/payment/refund/query

退款：
- OpenAPI 退款需要先在商户控制台 API安全 中开启退款权限。
- refundAmount 使用分为单位，10 表示 0.10 元。
- 退款接口返回 code=1000 只表示接口调用成功，退款最终结果以 data.status 为准。
- data.status=3 表示退款失败，失败原因读取 data.errorMessage。

申请退款示例：
```http
POST /open/payment/refund/create
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "orderId": "PAY202607080001000001",
  "refundNo": "R202607080001",
  "refundAmount": 10,
  "reason": "用户申请退款",
  "timestamp": "1783500003",
  "sign_type": "MD5",
  "sign": "md5签名"
}
```

申请退款返回示例：
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "refundId": "RF202607081230001A2B3C4D",
    "refundNo": "R202607080001",
    "orderId": "PAY202607080001000001",
    "merchantOrderNo": "P202607080001",
    "clientNo": "JP26070612345678",
    "merchantNo": "JP26070612345678",
    "refundAmount": 10,
    "amount": 10,
    "status": 1,
    "statusText": "处理中",
    "errorMessage": "",
    "createTime": "2026-07-08 12:30:00",
    "refundedAt": null
  }
}
```

退款查询示例：
```http
POST /open/payment/refund/query
Content-Type: application/json

{
  "clientNo": "JP26070612345678",
  "refundId": "RF202607081230001A2B3C4D",
  "refundNo": "R202607080001",
  "timestamp": "1783500004",
  "sign_type": "MD5",
  "sign": "md5签名"
}
```

退款失败返回示例：
```json
{
  "code": 1000,
  "message": "success",
  "data": {
    "refundId": "RF202607081230001A2B3C4D",
    "refundNo": "R202607080001",
    "orderId": "PAY202607080001000001",
    "merchantOrderNo": "P202607080001",
    "clientNo": "JP26070612345678",
    "merchantNo": "JP26070612345678",
    "refundAmount": 10,
    "amount": 10,
    "status": 3,
    "statusText": "退款失败",
    "errorMessage": "可用余额不足",
    "createTime": "2026-07-08 12:30:00",
    "refundedAt": null
  }
}
```

---

# MD5 签名与支付回调

签名：
1. 排除 sign、sign_type 和空值字段。
2. 剩余字段按 ASCII 升序排序。
3. 拼接为 key=value&key=value。
4. object 参数先转 JSON 字符串。
5. 商户 KEY 直接拼在待签名串末尾。
6. sign = md5(待签名串 + 商户 KEY).toLowerCase()

回调：
- 仅在配置 notifyUrl 时发送。
- 平台可能多次回调，业务处理必须幂等。
- 收到通知先验签，再校验金额、商户号和订单号。
- 支付成功状态是数值 2，不是字符串 paid 或 PAID。
- 处理成功后返回纯字符串 success。

支付通知示例：
```json
{
  "clientNo": "JP26070612345678",
  "orderId": "PAY202607080001000001",
  "merchantOrderNo": "P202607080001",
  "amount": 100,
  "status": 2,
  "goodsName": "测试商品",
  "payMethod": "wx",
  "payType": "jsapi",
  "param": "user_id=1001",
  "paidAt": "2026-07-08 12:30:00",
  "sign_type": "MD5",
  "sign": "md5签名"
}
```

支付回调示例：
```ts
import crypto from 'node:crypto'

function signParams(params: Record<string, any>, key: string) {
  const content = Object.keys(params)
    .filter(k => !['sign', 'sign_type'].includes(k) && params[k] !== '' && params[k] !== null && params[k] !== undefined)
    .sort()
    .map(k => k + '=' + (typeof params[k] === 'object' ? JSON.stringify(params[k]) : String(params[k])))
    .join('&')
  return crypto.createHash('md5').update(content + key).digest('hex')
}

export default defineEventHandler(async (event) => {
  const body = await readBody(event)
  const merchantKey = '你的商户KEY'

  if (signParams(body, merchantKey) !== String(body.sign || '').toLowerCase()) {
    return 'fail'
  }

  // 1. 校验 clientNo / orderId / merchantOrderNo / amount
  // 2. 判断订单是否已处理，保证幂等
  // 3. status=2 时更新本地订单为支付成功
  // 4. 记录支付流水

  return 'success'
})
```

---

# 给 AI 的实现任务

你现在要为“简付 JianPay”生成服务端支付接入代码。

必须实现：
1. MD5 签名函数。
2. 收银台下单函数。
3. API 下单函数。
4. 支付通知回调接口，包含验签、金额校验、订单幂等和返回 success。
5. 主动查单补偿函数。
6. 退款申请和退款查询函数。
7. 统一错误处理。

必须遵守：
- 商户 KEY 只能放在服务端。
- 支付成功不能依赖前端跳转，必须以回调或查单为准。
- 回调必须先验签，再校验订单、金额和商户号。
- 回调处理必须幂等。
- 回调成功后只返回纯字符串 success。
- notifyUrl 不填时必须使用主动查单确认支付状态。
- 退款结果以 data.status 为准，不以 code=1000 直接判断成功。

输出内容：
- 根据用户项目语言和框架输出可直接落地的代码。
- 没有项目上下文时，优先输出 Node.js / TypeScript 示例。
- 代码里用环境变量读取 clientNo 和 merchantKey。
- 给出必要的数据库订单状态更新伪代码。