所有端点
下方按功能分组列出所有 API 端点。点击查看完整参数与示例。
健康检查
GET
/health
无需鉴权
返回服务状态与版本信息。
curl https://pay.jnqj.net/api/v1/health
综合查询
POST
/query
scope: query
统一查询接口，支持 order / wallet_tx / balance 三种查询类型。
请求参数：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
query_type | string | 是 | order / wallet_tx / balance |
tx_no | string | order 必填 | 订单号 |
page | int | 否 | 页码，默认 1 |
per_page | int | 否 | 每页条数，默认 20，最大 50 |
GET
/balance
scope: query
查询当前密钥所属用户的双钱包余额（消费者钱包 + 商家钱包）。
{
"ok": true,
"data": {
"user_id": 2,
"jnqj_id": "JN-AB12-CD34",
"consumer": {
"balance": 500.00,
"frozen": 0.00,
"total_in": 1000.00,
"total_out": 500.00
},
"merchant": {
"balance": 1234.56,
"frozen": 100.00,
"total_in": 5000.00,
"total_out": 3765.44
},
"balance": 1234.56,
"frozen": 100.00,
"total_in": 5000.00,
"total_out": 3765.44
}
}
balance 等顶层字段为兼容旧版的快捷访问（取商家钱包），建议使用 consumer / merchant 对象分别获取。
GET
/transactions
scope: query
分页查询钱包流水。
Query 参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
page | int | 否 | 页码，默认 1 |
per_page | int | 否 | 每页条数，默认 20，最大 50 |
type | string | 否 | 类型筛选：recharge/consume/refund/transfer/withdraw/collection |
direction | string | 否 | 方向：in / out |
date_from | date | 否 | 开始日期 YYYY-MM-DD |
date_to | date | 否 | 结束日期 YYYY-MM-DD |
收款下单
POST
/collection
scope: collection
为商家创建一个收款订单，返回支付链接。链接有效期为 30 分钟。
请求体：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
amount | float | 是 | 金额（元），最低 0.01，最高 100000 |
merchant_id | int | 是 | 商家 ID（须属于当前密钥所有者） |
branch_id | int | 否 | 分店 ID |
title | string | 否 | 订单标题，默认「向 XX 付款」 |
notify_url | string | 否 | 支付成功异步回调地址 |
payer_id | int | 否 | 付款方用户 ID（一般不传，扫码时自动确定） |
idempotency_key | string | 建议 | 幂等键 |
成功响应：
{
"ok": true,
"data": {
"tx_no": "T202607291200001234ABCD",
"pay_url": "https://pay.jnqj.net/pay/T202607291200001234ABCD",
"pay_qrcode_url": "https://pay.jnqj.net/qrcode/T202607291200001234ABCD",
"amount": 29.90,
"title": "VIP会员月卡",
"merchant_id": 1,
"merchant_name": "金牛奇迹科技有限公司",
"expire_seconds": 1800
}
}
订单生命周期
GET
/order-lifecycle
scope: query
查询订单全生命周期：创建 → 支付 → 退款 → 结算，包含每个环节的时间、金额、状态变迁。
Query 参数：
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
tx_no | string | 是 | 订单号 |
curl -H "X-JNQJ-Key: $KEY_ID" \
-H "X-JNQJ-Secret: $SECRET" \
-H "X-JNQJ-Timestamp: $TIMESTAMP" \
-H "X-JNQJ-Nonce: $NONCE" \
-H "X-JNQJ-Signature: $SIGNATURE" \
"https://pay.jnqj.net/api/v1/order-lifecycle?tx_no=T202607291200001234ABCD"
退款
POST
/refund
scope: refund
对已支付的订单发起退款（全额或部分）。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
tx_no | string | 是 | 原订单号 |
refund_type | string | 是 | full / partial |
amount | float | partial 必填 | 部分退款金额 |
reason | string | 是 | 退款原因 |
pay_password | string | 是 | 支付密码（6 位数字） |
totp_code | string | 条件 | 已开启 2FA 时必填 |
idempotency_key | string | 建议 | 幂等键 |
部分退款将扣除 1% 手续费；全额退款免手续费。