sub2api/docs/ADMIN_PAYMENT_INTEGRATION_API.md

ADMIN_PAYMENT_INTEGRATION_API

单文件中英双语文档 / Single-file bilingual documentation (Chinese + English)

---

中文

目标

本文档用于对接外部支付系统（如 sub2apipay）与 Sub2API 的 Admin API，覆盖：

• 支付成功后充值
• 用户查询
• 人工余额修正
• 前端购买页参数透传

基础地址

• 生产：https://<your-domain>
• Beta：http://<your-server-ip>: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

请求体示例：

{
  "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 示例：

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

curl -s "${BASE}/api/v1/admin/users/123" \
  -H "x-api-key: ${KEY}"

3) 余额调整（已有接口）

POST /api/v1/admin/users/:id/balance

用途：人工补偿 / 扣减，支持 set / add / subtract。

请求体示例（扣减）：

{
  "balance": 100.0,
  "operation": "subtract",
  "notes": "manual correction"
}

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 或用户侧自定义页面 iframe URL 时，会统一追加：

• user_id
• token
• theme（light / dark）
• lang（例如 zh / en，用于向嵌入页传递当前界面语言）
• ui_mode（固定 embedded）

示例：

https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&lang=zh&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://<your-domain>
• Beta: http://<your-server-ip>:8084

Authentication

Recommended headers:

• x-api-key: admin-<64hex>
• Content-Type: application/json
• Idempotency-Key for idempotent endpoints

Note: Admin JWT can also access admin routes, but Admin API Key is recommended for server-to-server integration.

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.

Headers:

• x-api-key
• Idempotency-Key

Request body:

{
  "code": "s2p_cm1234567890",
  "type": "balance",
  "value": 100.0,
  "user_id": 123,
  "notes": "sub2apipay order: cm1234567890"
}

Idempotency behavior:

• Same code and same used_by: 200
• Same code but different used_by: 409
• Missing Idempotency-Key: 400 (IDEMPOTENCY_KEY_REQUIRED)

curl example:

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) Query User (optional pre-check)

GET /api/v1/admin/users/:id

curl -s "${BASE}/api/v1/admin/users/123" \
  -H "x-api-key: ${KEY}"

3) Balance Adjustment (existing API)

POST /api/v1/admin/users/:id/balance

Use case: manual correction with set / add / subtract.

Request body example (subtract):

{
  "balance": 100.0,
  "operation": "subtract",
  "notes": "manual correction"
}

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) Purchase / Custom Page URL query forwarding (iframe and new tab)

When Sub2API opens purchase_subscription_url or a user-facing custom page iframe URL, it appends:

• user_id
• token
• theme (light / dark)
• lang (for example zh / en, used to pass the current UI language to the embedded page)
• ui_mode (fixed: embedded)

Example:

https://pay.example.com/pay?user_id=123&token=<jwt>&theme=light&lang=zh&ui_mode=embedded

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

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