# 梨界支付中心 · LLM 友好版

> 这份文件给 AI 助手（ChatGPT / Claude / Gemini 等）使用，让 AI 能快速理解 lj-pay 协议并生成接入代码。

## 一句话介绍

lj-pay 是梨界矩阵的统一支付网关。业务后端通过 HMAC-SHA256 签名调用 5 个 HTTP API（创单 / 查单 / 取消 / 退款 / callback 验签），不直接对接微信 / 支付宝。

## 完整文档

- 公开 markdown：https://pay.ljmatrix.cn/docs/integration.md  ← 喂给 AI 用这个
- HTML 版：https://pay.ljmatrix.cn/docs/integration
- OpenAPI 3.0 JSON：https://pay.ljmatrix.cn/openapi.json

## 给 AI 的快速提示词模板

把下面这段贴给 ChatGPT / Claude / Gemini，AI 会一次性给你生成完整接入代码：

```
我要给项目 X 接入梨界支付中心。完整文档：https://pay.ljmatrix.cn/docs/integration.md

我的栈：[Next.js 15 / Express / Flask / Django / Laravel ...]
我的 callback 路径：[/api/internal/pay-callback]
我已注册 site_code = "[code]"，hmac_secret 在业务后端 .env

请基于上面的文档生成：
1. lib/lj-pay.{ts|py|php}（HMAC 签名 + create / refund / cancel / query 4 个 API）
2. callback endpoint（验签 + 幂等 + 金额校验 + 标已支付）
3. ¥0.01 端到端测试脚本

要求：
- 金额单位用「分」
- 验签用 raw body + timingSafeEqual（防时序攻击）
- callback 幂等（biz_order_no + event 去重）
- 全部代码自包含可直接跑
```

## HMAC 算法（一行总结）

签名 = HMAC-SHA256(secret, "METHOD\nPATH\nTIMESTAMP\nNONCE\nSITE\nSHA256(BODY)")

Header: X-Pay-Signature: sha256=<hex>

## 关键 Gotchas（容易踩的坑）

- 金额是「分」（int），不是「元」
- 验签必须用 raw body，不能 JSON.parse 后再 stringify
- HMAC path 必须含 query（按 key 排序后 URL-encode）
- 验签必须 timingSafeEqual（防时序攻击）
- callback 必须幂等（biz_order_no + event 去重）
- 业务侧 callback 必须返回 200 + {ok:true}，否则 pay 重试 8-11 次
- GET 的 body_hash = sha256("") = e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
- nonce 不能复用（5 分钟内）
- biz_order_no 一旦 EXPIRED/CANCELED 后重新支付要换新的 biz_order_no

## 5 个核心端点

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | https://pay.ljmatrix.cn/api/v1/order/create | 创建订单 |
| GET | https://pay.ljmatrix.cn/api/v1/order/by-biz-no/{biz} | 查单（按业务订单号） |
| GET | https://pay.ljmatrix.cn/api/v1/order/by-pay-no/{pay} | 查单（按支付订单号） |
| POST | https://pay.ljmatrix.cn/api/v1/order/cancel | 取消未支付订单 |
| POST | https://pay.ljmatrix.cn/api/v1/order/refund | 发起退款 |

## 支付方式（channel）

- wechat_native：微信扫码
- wechat_jsapi：微信公众号内
- alipay_page：支付宝 PC 网页
- alipay_wap：支付宝 H5
- alipay_qr：支付宝预创建扫码

## 状态机

PENDING → PAID / FAILED / EXPIRED / CANCELED
PAID → PARTIAL_REFUNDED / REFUNDED
异常：PAY_AFTER_CLOSE（关单后到达成功通知）

## 错误码（17 个）

INVALID_SIGNATURE / EXPIRED_TIMESTAMP / REPLAYED_NONCE / SITE_NOT_FOUND / SITE_DISABLED / INVALID_REQUEST / INVALID_AMOUNT / DUPLICATE_PENDING_ORDER / ORDER_ALREADY_PAID / ORDER_NOT_FOUND / ORDER_NOT_REFUNDABLE / REFUND_AMOUNT_EXCEEDED / CHANNEL_DISABLED / CHANNEL_NOT_IMPLEMENTED / CHANNEL_API_ERROR / WEBHOOK_INVALID / CALLBACK_URL_BLOCKED

详见 https://pay.ljmatrix.cn/docs/integration.md 第 10 节。

---

# 给业务方开发者的话

如果你是人，不是 AI：直接看 https://pay.ljmatrix.cn/docs/integration（HTML 版有交互的 HMAC 调试器、SDK 复制按钮、流程图）。

如果你想让 AI 帮你写：复制本页第二节的提示词模板。