Skip to content

Commit 2e88e23

Browse files
touwaerioltouwaeriol
committed
feat(frontend): append purchase query params and make integration doc bilingual
1 parent 39ca192 commit 2e88e23

2 files changed

Lines changed: 317 additions & 57 deletions

File tree

‎ADMIN_PAYMENT_INTEGRATION_API.md‎

Lines changed: 206 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,189 @@
1-
# Sub2API Admin API: Payment Integration
1+
# Sub2API Admin API: Payment Integration / 支付集成接口文档
22

3-
This document describes the minimum Admin API surface for external payment systems (for example, sub2apipay) to complete balance top-up and reconciliation.
3+
## 中文
44

5-
## Base URL
5+
### 概述
6+
7+
本文档描述外部支付系统（例如 sub2apipay）对接 Sub2API 时的最小 Admin API 集合，用于完成充值发放与对账。
8+
9+
### 基础地址
10+
11+
- 生产环境：`https://<your-domain>`
12+
- Beta 环境：`http://<your-server-ip>:8084`
13+
14+
### 认证方式
15+
16+
以下接口均建议使用：
17+
18+
- 请求头：`x-api-key: admin-<64hex>`（服务间调用推荐）
19+
- 请求头：`Content-Type: application/json`
20+
21+
说明：管理员 JWT 也可访问 admin 路由，但机器对机器调用建议使用 Admin API Key。
22+
23+
### 1) 一步完成：创建兑换码并兑换
24+
25+
`POST /api/v1/admin/redeem-codes/create-and-redeem`
26+
27+
用途：
28+
29+
- 原子化完成“创建固定兑换码 + 兑换给指定用户”。
30+
- 常用于支付回调成功后的自动充值。
31+
32+
必需请求头：
33+
34+
- `x-api-key`
35+
- `Idempotency-Key`
36+
37+
请求体：
38+
39+
```json
40+
{
41+
"code": "s2p_cm1234567890",
42+
"type": "balance",
43+
"value": 100.0,
44+
"user_id": 123,
45+
"notes": "sub2apipay order: cm1234567890"
46+
}
47+
```
48+
49+
规则：
50+
51+
- `code`：外部订单映射的确定性兑换码。
52+
- `type`：当前推荐使用 `balance`。
53+
- `value`：必须大于 0。
54+
- `user_id`：目标用户 ID。
55+
56+
幂等语义：
57+
58+
- 同一 `code` 且 `used_by` 一致：返回 `200`（幂等回放）。
59+
- 同一 `code` 但 `used_by` 不一致：返回 `409`（冲突）。
60+
- 缺少 `Idempotency-Key`：返回 `400`（`IDEMPOTENCY_KEY_REQUIRED`）。
61+
62+
示例：
63+
64+
```bash
65+
curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \
66+
-H "x-api-key: ${KEY}" \
67+
-H "Idempotency-Key: pay-cm1234567890-success" \
68+
-H "Content-Type: application/json" \
69+
-d '{
70+
"code":"s2p_cm1234567890",
71+
"type":"balance",
72+
"value":100.00,
73+
"user_id":123,
74+
"notes":"sub2apipay order: cm1234567890"
75+
}'
76+
```
77+
78+
### 2) 查询用户（可选前置检查）
79+
80+
`GET /api/v1/admin/users/:id`
81+
82+
用途：
83+
84+
- 支付成功后充值前，确认目标用户是否存在。
85+
86+
示例：
87+
88+
```bash
89+
curl -s "${BASE}/api/v1/admin/users/123" \
90+
-H "x-api-key: ${KEY}"
91+
```
92+
93+
### 3) 余额调整（已存在接口）
94+
95+
`POST /api/v1/admin/users/:id/balance`
96+
97+
用途：
98+
99+
- 复用现有管理员接口做人工纠偏。
100+
- 支持 `set`、`add`、`subtract`。
101+
102+
示例（扣减）：
103+
104+
```json
105+
{
106+
"balance": 100.0,
107+
"operation": "subtract",
108+
"notes": "manual correction"
109+
}
110+
```
111+
112+
```bash
113+
curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
114+
-H "x-api-key: ${KEY}" \
115+
-H "Idempotency-Key: balance-subtract-cm1234567890" \
116+
-H "Content-Type: application/json" \
117+
-d '{
118+
"balance":100.00,
119+
"operation":"subtract",
120+
"notes":"manual correction"
121+
}'
122+
```
123+
124+
### 4) 购买页跳转 URL Query 参数（iframe 与新窗口统一）
125+
126+
Sub2API 前端在打开 `purchase_subscription_url` 时，会给 iframe 和“新窗口打开”统一追加 query 参数，确保外部支付页拿到一致上下文。
127+
128+
追加参数：
129+
130+
- `user_id`：当前登录用户 ID
131+
- `token`：当前登录 JWT token
132+
- `theme`：当前主题（`light` / `dark`）
133+
- `ui_mode`：当前 UI 模式（固定 `embedded`）
134+
135+
示例：
136+
137+
```text
138+
https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&ui_mode=embedded
139+
```
140+
141+
### 5) 失败处理建议
142+
143+
- 支付状态与充值状态分开落库。
144+
- 收到并验证支付回调后，立即标记“支付成功”。
145+
- 支付成功但充值失败的订单应允许后续重试。
146+
- 重试时继续使用同一 `code`，并使用新的 `Idempotency-Key`。
147+
148+
### 6) `doc_url` 配置建议
149+
150+
Sub2API 已支持系统设置中的 `doc_url` 字段。
151+
152+
推荐配置：
153+
154+
- 查看链接：`https://github.com/Wei-Shaw/sub2api/blob/main/ADMIN_PAYMENT_INTEGRATION_API.md`
155+
- 下载链接：`https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md`
156+
157+
---
158+
159+
## English
160+
161+
### Overview
162+
163+
This document defines the minimum Admin API surface for integrating external payment systems (for example, sub2apipay) with Sub2API for recharge fulfillment and reconciliation.
164+
165+
### Base URL
6166

7167
- Production: `https://<your-domain>`
8168
- Beta: `http://<your-server-ip>:8084`
9169

10-
All endpoints below use:
170+
### Authentication
11171

12-
- Header: `x-api-key: admin-<64hex>` (recommended for server-to-server)
13-
- Header: `Content-Type: application/json`
172+
Recommended headers:
14173

15-
Note: Admin JWT is also accepted by admin routes, but machine-to-machine integration should use admin API key.
174+
- `x-api-key: admin-<64hex>` (recommended for server-to-server calls)
175+
- `Content-Type: application/json`
16176

17-
## 1) Create + Redeem in One Step
177+
Note: Admin JWT is also accepted by admin routes, but Admin API key is recommended for machine integrations.
178+
179+
### 1) One-step Create + Redeem
18180

19181
`POST /api/v1/admin/redeem-codes/create-and-redeem`
20182

21183
Purpose:
22184

23-
- Atomically create a deterministic redeem code and redeem it to a target user.
24-
- Typical usage: called after payment callback succeeds.
185+
- Atomically create a deterministic redeem code and redeem it to the target user.
186+
- Typical usage: called right after payment callback success.
25187

26188
Required headers:
27189

@@ -42,16 +204,16 @@ Request body:
42204

43205
Rules:
44206

45-
- `code`: external deterministic order-mapped code.
46-
- `type`: currently recommended `balance`.
47-
- `value`: must be `> 0`.
207+
- `code`: deterministic code mapped from external order id.
208+
- `type`: `balance` is the recommended type.
209+
- `value`: must be greater than 0.
48210
- `user_id`: target user id.
49211

50-
Idempotency semantics:
212+
Idempotency behavior:
51213

52-
- Same `code`, same `used_by` user: return `200` (idempotent replay).
53-
- Same `code`, different `used_by` user: return `409` conflict.
54-
- Missing `Idempotency-Key`: return `400` (`IDEMPOTENCY_KEY_REQUIRED`).
214+
- Same `code` and same `used_by`: `200` (idempotent replay).
215+
- Same `code` and different `used_by`: `409` (conflict).
216+
- Missing `Idempotency-Key`: `400` (`IDEMPOTENCY_KEY_REQUIRED`).
55217

56218
Example:
57219

@@ -69,13 +231,13 @@ curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \
69231
}'
70232
```
71233

72-
## 2) Query User (Optional Pre-check)
234+
### 2) Query User (Optional Pre-check)
73235

74236
`GET /api/v1/admin/users/:id`
75237

76238
Purpose:
77239

78-
- Check whether target user exists before payment finalize/retry.
240+
- Verify target user existence before final recharge/retry.
79241

80242
Example:
81243

@@ -84,13 +246,13 @@ curl -s "${BASE}/api/v1/admin/users/123" \
84246
-H "x-api-key: ${KEY}"
85247
```
86248

87-
## 3) Balance Adjustment (Existing Interface)
249+
### 3) Balance Adjustment (Existing API)
88250

89251
`POST /api/v1/admin/users/:id/balance`
90252

91253
Purpose:
92254

93-
- Existing reusable admin interface for manual correction.
255+
- Reuse existing admin endpoint for manual reconciliation.
94256
- Supports `set`, `add`, `subtract`.
95257

96258
Request body example (`subtract`):
@@ -117,18 +279,35 @@ curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
117279
}'
118280
```
119281

120-
## 4) Error Handling Recommendations
282+
### 4) Purchase URL Query Parameters (Iframe + New Tab)
283+
284+
When Sub2API frontend opens `purchase_subscription_url`, it appends the same query parameters for both iframe and “open in new tab” to keep context consistent.
285+
286+
Appended parameters:
287+
288+
- `user_id`: current logged-in user id
289+
- `token`: current logged-in JWT token
290+
- `theme`: current theme (`light` / `dark`)
291+
- `ui_mode`: UI mode (fixed `embedded`)
292+
293+
Example:
294+
295+
```text
296+
https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&ui_mode=embedded
297+
```
298+
299+
### 5) Failure Handling Recommendations
121300

122-
- Persist upstream payment result independently from recharge result.
301+
- Store payment state and recharge state separately.
123302
- Mark payment success immediately after callback verification.
124-
- If recharge fails after payment success, keep order retryable by admin operation.
125-
- For retry, always reuse deterministic `code` + new `Idempotency-Key`.
303+
- Keep orders retryable when payment succeeded but recharge failed.
304+
- Reuse the same deterministic `code` and a new `Idempotency-Key` when retrying.
126305

127-
## 5) Suggested `doc_url` Setting
306+
### 6) Suggested `doc_url` Value
128307

129308
Sub2API already supports `doc_url` in system settings.
130309

131310
Recommended values:
132311

133312
- View URL: `https://github.com/Wei-Shaw/sub2api/blob/main/ADMIN_PAYMENT_INTEGRATION_API.md`
134-
- Direct download URL: `https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md`
313+
- Download URL: `https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/ADMIN_PAYMENT_INTEGRATION_API.md`

0 commit comments

Comments
 (0)