订单API文档

订单创建、查询、回调通知接口说明

安全说明：所有订单接口都需要 api_token 验证，token 通过会员登录获取，不可伪造。

1. 接口地址

https://pay.qianxi.xin/api/order/

2. 鉴权方式

所有订单接口必须携带 api_token 参数，支持以下方式传递：

方式示例
URL参数?api_token=xxxx
POST表单api_token=xxxx
POST JSON{"api_token": "xxxx"}

3. 创建订单

POST /api/order/create?api_token=xxxx

智能金额调整：系统会自动确保订单金额唯一性。5分钟内有相同金额的待支付订单时，自动加0.01元，避免支付匹配冲突。
参数必填类型说明
api_token是string会员API Token（鉴权必填）
title是string商品名称
amount是float金额(元)，系统会自动调整确保唯一性
description否string商品描述
pay_type否string支付方式: wechat/alipay/any(默认)
expire_minutes否int过期分钟数(默认5,最长1440)
notify_url否string支付成功回调地址
extra否string扩展数据(JSON)
金额自动调整规则
场景处理方式
5分钟内无相同金额的待支付订单使用原始金额创建订单
5分钟内有相同金额的待支付订单自动加0.01元，直到找到可用金额
原订单支付成功/取消/过期该金额可再次使用
最多调整次数100次（最多加1元）

示例场景：

用户A请求创建 ¥1.00 订单 → 创建成功，金额 ¥1.00
用户A再次请求创建 ¥1.00 订单 → 自动调整为 ¥1.01
用户A第三次请求 ¥1.00 → 自动调整为 ¥1.02
第一个订单 ¥1.00 支付成功 → 下次可再次创建 ¥1.00

请求示例：

POST /api/order/create?api_token=你的API_TOKEN
Content-Type: application/json

{
    "title": "VIP会员月卡",
    "description": "一个月VIP会员服务",
    "amount": 29.90,
    "pay_type": "any",
    "expire_minutes": 5,
    "notify_url": "https://your-site.com/callback"
}

返回示例：

{
    "code": 0,
    "msg": "订单创建成功（原金额¥1.00已调整，避免冲突）",
    "data": {
        "order_id": 1,
        "order_no": "ORD20260530143022123456",
        "title": "VIP会员月卡",
        "description": "一个月VIP会员服务",
        "amount": 1.01,
        "original_amount": 1.00,
        "amount_adjusted": true,
        "pay_type": "any",
        "status": "pending",
        "expire_at": "2026-05-30 15:00:22",
        "expire_minutes": 5,
        "created_at": "2026-05-30 14:30:22",
        "qrcodes": [
            {
                "id": 1,
                "type": "wechat",
                "name": "微信收款码",
                "image_path": "/qrcode/wechat1.png",
                "qr_content": "wxp://f2f0..."
            },
            {
                "id": 2,
                "type": "alipay",
                "name": "支付宝收款码",
                "image_path": "/qrcode/alipay1.png",
                "qr_content": "https://qr.alipay.com/..."
            }
        ]
    }
}

4. 订单列表

GET /api/order/list?api_token=xxxx&page=1&size=20

参数必填说明
api_token是会员API Token
page否页码(默认1)
size否每页条数(默认20,最大100)
status否筛选状态: pending/paid/expired/cancelled/refunded
keyword否搜索关键词(商品名/订单号/备注)
start_date否开始日期(2026-01-01)
end_date否结束日期(2026-12-31)

5. 订单详情

GET /api/order/detail?api_token=xxxx&order_no=ORD20260530143022123456

返回订单完整信息及操作日志。

6. 取消订单

POST /api/order/cancel?api_token=xxxx

{
    "order_no": "ORD20260530143022123456"
}
只能取消待支付(pending)状态的订单

7. 退款订单

POST /api/order/refund?api_token=xxxx

{
    "order_no": "ORD20260530143022123456",
    "reason": "用户申请退款"
}
只能退款已支付(paid)状态的订单

8. 手动重试回调

POST /api/order/notify?api_token=xxxx

{
    "order_no": "ORD20260530143022123456"
}

9. 订单统计

GET /api/order/stats?api_token=xxxx&period=today

period值说明
today今天
week最近7天
month最近30天
all全部

10. 订单状态说明

状态说明
pending待支付
paid已支付
expired已过期
cancelled已取消
refunded已退款

11. 回调通知格式

订单支付成功后，系统会向 notify_url 发送 POST 请求：

{
    "order_no": "ORD20260530143022123456",
    "title": "VIP会员月卡",
    "amount": 29.90,
    "pay_type": "alipay",
    "status": "paid",
    "payer": "付款人昵称",
    "remark": "付款备注",
    "paid_at": "2026-05-30 14:31:05",
    "created_at": "2026-05-30 14:30:22",
    "timestamp": 1748615465
}
收到回调后请返回 HTTP 200，否则系统会重试通知。

常见问题

Q: 创建订单返回金额与请求不一致？

A: 系统会自动调整金额避免冲突。返回的 amount 是实际创建的金额，original_amount 是你请求的原始金额，amount_adjusted 为 true 表示已调整。

Q: 订单一直显示待支付？

A: 订单默认5分钟过期。请确认：1) 付款金额与订单金额完全一致（精确到分）；2) 付款在过期时间内完成；3) App已正常上报收款到服务器。

Q: 收到回调但缺少 status 字段？

A: 回调数据包含 status: "paid" 字段。如果第三方系统需要兼容，建议同时检查 status 和 paid_at 字段。

Q: 如何获取 api_token？

A: 通过会员登录接口 POST /api/member/login 获取，或在会员中心查看。

Q: 订单过期后会自动处理吗？

A: 会。系统有定时任务每分钟检查，将过期订单标记为 expired。也可以通过 Cron 脚本 cron_order_expire.php 手动执行。

Q: 同一时间能创建多少订单？

A: 无限制。但系统会自动调整金额确保每个订单金额唯一，最多调整100次（加1元）。

返回首页 会员中心