{ "openapi": "3.0.3", "info": { "title": "方传智付 开放 API", "version": "v1", "description": "HMAC-SHA256 签名鉴权的开放接口。详见 /docs/api。" }, "servers": [ { "url": "http://localhost:3000/openapi/v1", "description": "本地 / 示例" } ], "security": [ { "fcHeaders": [] } ], "components": { "securitySchemes": { "fcHeaders": { "type": "apiKey", "in": "header", "name": "X-Sign", "description": "配合 X-App-Id / X-Timestamp / X-Nonce 头与 HMAC-SHA256 签名。" } } }, "tags": [ { "name": "公开" }, { "name": "需要鉴权" } ], "paths": { "/openapi/v1/ping": { "get": { "summary": "连通性探测", "description": "校验签名与鉴权是否通过，并返回服务器时间，可用于本地时间校准。无需业务 Scope，但仍需签名。", "operationId": "ping", "tags": [ "公开" ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {}, "request_id": { "type": "string" } } }, "example": { "code": "0", "message": "success", "data": { "app_id": "fcxxxxxxxx", "server_time": 1700000000 }, "request_id": "req-xxx" } } } } } } }, "/openapi/v1/system/status": { "get": { "summary": "支付可用状态", "description": "返回全局支付服务状态，供第三方在前端展示「暂停 / 正常」提示。无需业务 Scope。", "operationId": "system-status", "tags": [ "公开" ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {}, "request_id": { "type": "string" } } }, "example": { "code": "0", "message": "success", "data": { "status": "normal" }, "request_id": "req-xxx" } } } } } } }, "/openapi/v1/balance": { "get": { "summary": "查询用户余额", "description": "按 user_id 或 phone 查询用户账户余额与实名 / 账户状态。", "operationId": "balance", "tags": [ "需要鉴权" ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "用户 ID（与 phone 二选一）", "example": 12345 }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "注册手机号，1[3-9] 开头 11 位", "example": "13800000001" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {}, "request_id": { "type": "string" } } }, "example": { "code": "0", "message": "success", "data": { "user_id": 12345, "balance_fen": 50000, "balance": "500.00", "currency": "CNY", "kyc_status": "verified", "status": "active" }, "request_id": "req-xxx" } } } }, "default": { "description": "错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } }, "security": [ { "fcHeaders": [ "balance.read" ] } ] } }, "/openapi/v1/transactions": { "get": { "summary": "查询交易流水", "description": "分页查询指定用户的交易流水，可按日期区间过滤。", "operationId": "transactions", "tags": [ "需要鉴权" ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "用户 ID（与 phone 二选一）", "example": 12345 }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "注册手机号", "example": "13800000001" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "页码，1~1000，默认 1" }, { "name": "page_size", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "每页条数，1~50，默认 20" }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "起始日期 YYYY-MM-DD" }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "结束日期 YYYY-MM-DD" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {}, "request_id": { "type": "string" } } }, "example": { "code": "0", "message": "success", "data": { "user_id": 12345, "total": 1, "page": 1, "page_size": 20, "list": [ { "tx_no": "RC...", "type": "recharge", "direction": "credit", "amount_fen": 5000, "amount": "50.00", "status": "success", "remark": "", "created_at": "2026-01-01T00:00:00.000Z" } ] }, "request_id": "req-xxx" } } } }, "default": { "description": "错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } }, "security": [ { "fcHeaders": [ "transactions.read" ] } ] } }, "/openapi/v1/pay": { "post": { "summary": "代付 / 扣款", "description": "从指定用户余额扣减金额（代付）。out_trade_no 为幂等键，重复提交同号返回首次结果（replayed=true）。", "operationId": "pay", "tags": [ "需要鉴权" ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {}, "request_id": { "type": "string" } } }, "example": { "code": "0", "message": "success", "data": { "tx_no": "RC...", "user_id": 12345, "amount_fen": 5000, "amount": "50.00", "balance_fen": 45000, "status": "success", "replayed": false }, "request_id": "req-xxx" } } } }, "default": { "description": "错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } }, "security": [ { "fcHeaders": [ "pay.debit" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "目标用户 ID（与 phone 二选一）", "example": 12345 }, "phone": { "type": "string", "description": "目标用户手机号", "example": "13800000001" }, "amount_fen": { "type": "integer", "description": "金额（分，正整数，上限 100000000）" }, "amount": { "type": "string", "description": "金额（元，格式 \\d{1,7}(\\.\\d{1,2})?）" }, "out_trade_no": { "type": "string", "description": "商户订单号，6~64 位字母/数字/下划线/连字符，幂等键", "example": "ORDER_20260101_001" }, "remark": { "type": "string", "description": "备注，≤60 字" } }, "required": [ "out_trade_no" ] } } } } } }, "/openapi/v1/recharge": { "post": { "summary": "为用户入账", "description": "为指定用户增加余额（入账）。out_trade_no 为幂等键，重复提交同号返回首次结果（replayed=true）。", "operationId": "recharge", "tags": [ "需要鉴权" ], "parameters": [], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {}, "request_id": { "type": "string" } } }, "example": { "code": "0", "message": "success", "data": { "tx_no": "RC...", "user_id": 12345, "amount_fen": 5000, "amount": "50.00", "balance_fen": 55000, "status": "success", "replayed": false }, "request_id": "req-xxx" } } } }, "default": { "description": "错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } }, "security": [ { "fcHeaders": [ "wallet.recharge" ] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "user_id": { "type": "integer", "description": "目标用户 ID（与 phone 二选一）", "example": 12345 }, "phone": { "type": "string", "description": "目标用户手机号", "example": "13800000001" }, "amount_fen": { "type": "integer", "description": "金额（分，正整数）" }, "amount": { "type": "string", "description": "金额（元）" }, "out_trade_no": { "type": "string", "description": "商户订单号，6~64 位，幂等键", "example": "RECH_20260101_001" }, "remark": { "type": "string", "description": "备注，≤60 字" } }, "required": [ "out_trade_no" ] } } } } } }, "/openapi/v1/kyc/status": { "get": { "summary": "查询实名状态", "description": "按 user_id 或 phone 查询用户实名认证状态。", "operationId": "kyc-status", "tags": [ "需要鉴权" ], "parameters": [ { "name": "user_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "用户 ID（与 phone 二选一）", "example": 12345 }, { "name": "phone", "in": "query", "required": false, "schema": { "type": "string" }, "description": "注册手机号", "example": "13800000001" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "data": {}, "request_id": { "type": "string" } } }, "example": { "code": "0", "message": "success", "data": { "user_id": 12345, "kyc_status": "verified", "verified": true }, "request_id": "req-xxx" } } } }, "default": { "description": "错误", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } } } } } }, "security": [ { "fcHeaders": [ "kyc.read" ] } ] } } } }