From 7af00864b3c7eccc0512b54a9a32acb69a28e733 Mon Sep 17 00:00:00 2001 From: erio Date: Sun, 1 Mar 2026 00:41:38 +0800 Subject: [PATCH] feat(admin): add create-and-redeem API and payment integration docs --- ADMIN_PAYMENT_INTEGRATION_API.md | 225 ++++++++----------------------- 1 file changed, 59 insertions(+), 166 deletions(-) diff --git a/ADMIN_PAYMENT_INTEGRATION_API.md b/ADMIN_PAYMENT_INTEGRATION_API.md index 4cc21594..fa2ff2bc 100644 --- a/ADMIN_PAYMENT_INTEGRATION_API.md +++ b/ADMIN_PAYMENT_INTEGRATION_API.md @@ -1,159 +1,35 @@ -# ADMIN_PAYMENT_INTEGRATION_API +# Sub2API Admin API: Payment Integration -> 单文件中英双语文档 / Single-file bilingual documentation (Chinese + English) +This document describes the minimum Admin API surface for external payment systems (for example, sub2apipay) to complete balance top-up and reconciliation. ---- +## Base URL -## 中文 - -### 目标 -本文档用于对接外部支付系统（如 `sub2apipay`）与 Sub2API 的 Admin API，覆盖： -- 支付成功后充值 -- 用户查询 -- 人工余额修正 -- 前端购买页参数透传 - -### 基础地址 -- 生产：`https://` -- Beta：`http://:8084` - -### 认证 -推荐使用： -- `x-api-key: admin-<64hex>` -- `Content-Type: application/json` -- 幂等接口额外传：`Idempotency-Key` - -说明：管理员 JWT 也可访问 admin 路由，但服务间调用建议使用 Admin API Key。 - -### 1) 一步完成创建并兑换 -`POST /api/v1/admin/redeem-codes/create-and-redeem` - -用途：原子完成“创建兑换码 + 兑换到指定用户”。 - -请求头： -- `x-api-key` -- `Idempotency-Key` - -请求体示例： -```json -{ - "code": "s2p_cm1234567890", - "type": "balance", - "value": 100.0, - "user_id": 123, - "notes": "sub2apipay order: cm1234567890" -} -``` - -幂等语义： -- 同 `code` 且 `used_by` 一致：`200` -- 同 `code` 但 `used_by` 不一致：`409` -- 缺少 `Idempotency-Key`：`400`（`IDEMPOTENCY_KEY_REQUIRED`） - -curl 示例： -```bash -curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \ - -H "x-api-key: ${KEY}" \ - -H "Idempotency-Key: pay-cm1234567890-success" \ - -H "Content-Type: application/json" \ - -d '{ - "code":"s2p_cm1234567890", - "type":"balance", - "value":100.00, - "user_id":123, - "notes":"sub2apipay order: cm1234567890" - }' -``` - -### 2) 查询用户（可选前置校验） -`GET /api/v1/admin/users/:id` - -```bash -curl -s "${BASE}/api/v1/admin/users/123" \ - -H "x-api-key: ${KEY}" -``` - -### 3) 余额调整（已有接口） -`POST /api/v1/admin/users/:id/balance` - -用途：人工补偿 / 扣减，支持 `set` / `add` / `subtract`。 - -请求体示例（扣减）： -```json -{ - "balance": 100.0, - "operation": "subtract", - "notes": "manual correction" -} -``` - -```bash -curl -X POST "${BASE}/api/v1/admin/users/123/balance" \ - -H "x-api-key: ${KEY}" \ - -H "Idempotency-Key: balance-subtract-cm1234567890" \ - -H "Content-Type: application/json" \ - -d '{ - "balance":100.00, - "operation":"subtract", - "notes":"manual correction" - }' -``` - -### 4) 购买页 URL Query 透传（iframe / 新窗口一致） -当 Sub2API 打开 `purchase_subscription_url` 时，会统一追加： -- `user_id` -- `token` -- `theme`（`light` / `dark`） -- `ui_mode`（固定 `embedded`） - -示例： -```text -https://pay.example.com/pay?user_id=123&token=&theme=light&ui_mode=embedded -``` - -### 5) 失败处理建议 -- 支付成功与充值成功分状态落库 -- 回调验签成功后立即标记“支付成功” -- 支付成功但充值失败的订单允许后续重试 -- 重试保持相同 `code`，并使用新的 `Idempotency-Key` - -### 6) `doc_url` 配置建议 -- 查看链接：`https://github.com/Wei-Shaw/sub2api/blob/main/ADMIN_PAYMENT_INTEGRATION_API.md` -- 下载链接：`https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md` - ---- - -## English - -### Purpose -This document describes the minimal Sub2API Admin API surface for external payment integrations (for example, `sub2apipay`), including: -- Recharge after payment success -- User lookup -- Manual balance correction -- Purchase page query parameter forwarding - -### Base URL - Production: `https://` - Beta: `http://:8084` -### Authentication -Recommended headers: -- `x-api-key: admin-<64hex>` -- `Content-Type: application/json` -- `Idempotency-Key` for idempotent endpoints +All endpoints below use: -Note: Admin JWT can also access admin routes, but Admin API Key is recommended for server-to-server integration. +- Header: `x-api-key: admin-<64hex>` (recommended for server-to-server) +- Header: `Content-Type: application/json` + +Note: Admin JWT is also accepted by admin routes, but machine-to-machine integration should use admin API key. + +## 1) Create + Redeem in One Step -### 1) Create and Redeem in one step `POST /api/v1/admin/redeem-codes/create-and-redeem` -Use case: atomically create a redeem code and redeem it to a target user. +Purpose: + +- Atomically create a deterministic redeem code and redeem it to a target user. +- Typical usage: called after payment callback succeeds. + +Required headers: -Headers: - `x-api-key` - `Idempotency-Key` Request body: + ```json { "code": "s2p_cm1234567890", @@ -164,12 +40,21 @@ Request body: } ``` -Idempotency behavior: -- Same `code` and same `used_by`: `200` -- Same `code` but different `used_by`: `409` -- Missing `Idempotency-Key`: `400` (`IDEMPOTENCY_KEY_REQUIRED`) +Rules: + +- `code`: external deterministic order-mapped code. +- `type`: currently recommended `balance`. +- `value`: must be `> 0`. +- `user_id`: target user id. + +Idempotency semantics: + +- Same `code`, same `used_by` user: return `200` (idempotent replay). +- Same `code`, different `used_by` user: return `409` conflict. +- Missing `Idempotency-Key`: return `400` (`IDEMPOTENCY_KEY_REQUIRED`). + +Example: -curl example: ```bash curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \ -H "x-api-key: ${KEY}" \ @@ -184,20 +69,32 @@ curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \ }' ``` -### 2) Query User (optional pre-check) +## 2) Query User (Optional Pre-check) + `GET /api/v1/admin/users/:id` +Purpose: + +- Check whether target user exists before payment finalize/retry. + +Example: + ```bash curl -s "${BASE}/api/v1/admin/users/123" \ -H "x-api-key: ${KEY}" ``` -### 3) Balance Adjustment (existing API) +## 3) Balance Adjustment (Existing Interface) + `POST /api/v1/admin/users/:id/balance` -Use case: manual correction with `set` / `add` / `subtract`. +Purpose: + +- Existing reusable admin interface for manual correction. +- Supports `set`, `add`, `subtract`. Request body example (`subtract`): + ```json { "balance": 100.0, @@ -206,6 +103,8 @@ Request body example (`subtract`): } ``` +Example: + ```bash curl -X POST "${BASE}/api/v1/admin/users/123/balance" \ -H "x-api-key: ${KEY}" \ @@ -218,24 +117,18 @@ curl -X POST "${BASE}/api/v1/admin/users/123/balance" \ }' ``` -### 4) Purchase URL query forwarding (iframe and new tab) -When Sub2API opens `purchase_subscription_url`, it appends: -- `user_id` -- `token` -- `theme` (`light` / `dark`) -- `ui_mode` (fixed: `embedded`) +## 4) Error Handling Recommendations -Example: -```text -https://pay.example.com/pay?user_id=123&token=&theme=light&ui_mode=embedded -``` +- Persist upstream payment result independently from recharge result. +- Mark payment success immediately after callback verification. +- If recharge fails after payment success, keep order retryable by admin operation. +- For retry, always reuse deterministic `code` + new `Idempotency-Key`. -### 5) Failure handling recommendations -- Persist payment success and recharge success as separate states -- Mark payment as successful immediately after verified callback -- Allow retry for orders with payment success but recharge failure -- Keep the same `code` for retry, and use a new `Idempotency-Key` +## 5) Suggested `doc_url` Setting + +Sub2API already supports `doc_url` in system settings. + +Recommended values: -### 6) Recommended `doc_url` - View URL: `https://github.com/Wei-Shaw/sub2api/blob/main/ADMIN_PAYMENT_INTEGRATION_API.md` -- Download URL: `https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md` +- Direct download URL: `https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md`