{ "openapi": "3.0.3", "info": { "title": "梨界支付中心 API", "version": "1.0.0", "description": "梨界矩阵统一支付网关。业务方通过 HMAC-SHA256 签名调用 5 个核心 API。完整文档：https://pay.ljmatrix.cn/docs/integration", "contact": { "name": "梨界支付", "url": "https://pay.ljmatrix.cn/docs" } }, "servers": [ { "url": "https://pay.ljmatrix.cn" } ], "security": [ { "HmacAuth": [] } ], "components": { "securitySchemes": { "HmacAuth": { "type": "apiKey", "in": "header", "name": "X-Pay-Signature", "description": "HMAC-SHA256 over 6 fields: METHOD, PATH_WITH_QUERY, TIMESTAMP, NONCE, SITE_CODE, SHA256_HEX(RAW_BODY). Header value is `sha256=`. Also send X-Pay-Site, X-Pay-Timestamp, X-Pay-Nonce." } }, "schemas": { "Channel": { "type": "string", "enum": [ "wechat_native", "wechat_jsapi", "alipay_pc", "alipay_page", "alipay_wap", "alipay_qr" ], "description": "支付通道。alipay_pc 与 alipay_page 等价（前者是业务方惯用，后者是历史命名），均路由到 alipay.trade.page.pay。" }, "OrderStatus": { "type": "string", "enum": [ "PENDING", "PAID", "FAILED", "REFUNDED", "PARTIAL_REFUNDED", "CANCELED", "EXPIRED", "PAY_AFTER_CLOSE" ] }, "RefundStatus": { "type": "string", "enum": [ "PROCESSING", "SUCCESS", "FAILED", "UNKNOWN" ] }, "ErrorCode": { "type": "string", "enum": [ "INVALID_SIGNATURE", "EXPIRED_TIMESTAMP", "REPLAYED_NONCE", "SITE_NOT_FOUND", "SITE_DISABLED", "RATE_LIMITED", "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" ] }, "ErrorResponse": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } } }, "CreateOrderRequest": { "type": "object", "required": [ "biz_order_no", "amount_fen", "channel", "subject" ], "properties": { "biz_order_no": { "type": "string", "maxLength": 128, "description": "业务订单号" }, "amount_fen": { "type": "integer", "minimum": 1, "description": "金额（分）" }, "currency": { "type": "string", "default": "CNY" }, "channel": { "$ref": "#/components/schemas/Channel" }, "subject": { "type": "string", "maxLength": 127 }, "client_ip": { "type": "string", "maxLength": 64 }, "user_agent": { "type": "string", "maxLength": 512 }, "payer_openid": { "type": "string", "maxLength": 128, "description": "wechat_jsapi 必填" }, "return_url": { "type": "string", "maxLength": 512, "description": "支付宝同步跳转 URL。【条件必填】alipay_pc / alipay_wap 必传，否则用户付完款支付宝把浏览器停在'付款成功 3 秒后自动返回商户'页 → 没跳转目标 → UX 卡死。建议传业务方 checkout / 订单详情页。扫码通道（wechat_native / alipay_qr）不需要。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "透传字段，回调时原样返回" } } }, "CreateOrderResponse": { "type": "object", "properties": { "order_no": { "type": "string", "description": "pay 内部订单号 lp_xxx" }, "biz_order_no": { "type": "string" }, "channel": { "$ref": "#/components/schemas/Channel" }, "amount_fen": { "type": "integer" }, "expires_at": { "type": "integer", "description": "Unix 秒" }, "instructions": { "$ref": "#/components/schemas/Instructions" } } }, "Instructions": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "QR", "REDIRECT", "JSAPI" ] }, "qr_data_url": { "type": "string", "description": "QR 类型：PNG base64 data URL" }, "raw_pay_url": { "type": "string", "description": "QR 类型：原始 weixin:// scheme 或类似" }, "redirect_url": { "type": "string", "description": "REDIRECT 类型：跳转 URL" }, "jsapi_params": { "type": "object", "description": "JSAPI 类型：调起参数对象" } } }, "OrderInfo": { "type": "object", "properties": { "order_no": { "type": "string" }, "biz_order_no": { "type": "string" }, "channel": { "$ref": "#/components/schemas/Channel" }, "status": { "$ref": "#/components/schemas/OrderStatus" }, "amount_fen": { "type": "integer" }, "paid_amount_fen": { "type": "integer" }, "refunded_fen": { "type": "integer" }, "channel_trade_no": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "paid_at": { "type": "string", "format": "date-time" } } }, "RefundRequest": { "type": "object", "required": [ "biz_order_no", "out_refund_no", "refund_fen" ], "properties": { "biz_order_no": { "type": "string", "maxLength": 128 }, "out_refund_no": { "type": "string", "maxLength": 128, "description": "业务退款号，唯一" }, "refund_fen": { "type": "integer", "minimum": 1 }, "reason": { "type": "string", "maxLength": 255 } } }, "RefundResponse": { "type": "object", "properties": { "refund_no": { "type": "string", "description": "pay 内部退款号 lpr_xxx" }, "out_refund_no": { "type": "string" }, "status": { "$ref": "#/components/schemas/RefundStatus" }, "refund_fen": { "type": "integer" }, "channel_refund_id": { "type": "string" } } }, "CancelRequest": { "type": "object", "required": [ "biz_order_no" ], "properties": { "biz_order_no": { "type": "string", "maxLength": 128 } } } }, "responses": { "InvalidRequest": { "description": "请求参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "HMAC 签名 / 时间戳 / nonce 验证失败", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "资源不存在", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "订单冲突（已存在 PENDING / 已支付）", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UpstreamError": { "description": "上游渠道错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "paths": { "/api/v1/order/create": { "post": { "summary": "创建支付订单", "tags": [ "Order" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderRequest" } } } }, "responses": { "200": { "description": "创建成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrderResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/v1/order/by-biz-no/{biz_order_no}": { "get": { "summary": "按业务订单号查询", "tags": [ "Order" ], "parameters": [ { "name": "biz_order_no", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 128 } } ], "responses": { "200": { "description": "订单信息", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInfo" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/order/by-pay-no/{order_no}": { "get": { "summary": "按支付中心订单号查询", "tags": [ "Order" ], "parameters": [ { "name": "order_no", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "订单信息", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderInfo" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/order/cancel": { "post": { "summary": "取消未支付订单", "tags": [ "Order" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelRequest" } } } }, "responses": { "200": { "description": "已取消" }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/order/refund": { "post": { "summary": "发起退款", "tags": [ "Refund" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundRequest" } } } }, "responses": { "200": { "description": "退款受理", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" } } } }, "400": { "$ref": "#/components/responses/InvalidRequest" }, "404": { "$ref": "#/components/responses/NotFound" } } } } } }