This document describes the minimal Sub2API Admin API surface for external payment integrations (for example, `sub2apipay`), including:
This document defines the minimum Admin API surface for integrating external payment systems (for example, sub2apipay) with Sub2API for recharge fulfillment and reconciliation.
- Recharge after payment success
- User lookup
- Manual balance correction
- Purchase page query parameter forwarding
### Base URL
### Base URL
- Production: `https://<your-domain>`
- Production: `https://<your-domain>`
- Beta: `http://<your-server-ip>:8084`
- Beta: `http://<your-server-ip>:8084`
### Authentication
### Authentication
Recommended headers:
Recommended headers:
-`x-api-key: admin-<64hex>`
-`x-api-key: admin-<64hex>` (recommended for server-to-server calls)
-`Content-Type: application/json`
-`Content-Type: application/json`
-`Idempotency-Key` for idempotent endpoints
Note: Admin JWT is also accepted by admin routes, but Admin API key is recommended for machine integrations.
Note: Admin JWT can also access admin routes, but Admin API Key is recommended for server-to-server integration.
curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem"\
curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem"\
-H"x-api-key: ${KEY}"\
-H"x-api-key: ${KEY}"\
...
@@ -231,32 +184,20 @@ curl -X POST "${BASE}/api/v1/admin/redeem-codes/create-and-redeem" \
...
@@ -231,32 +184,20 @@ 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`
`GET /api/v1/admin/users/:id`
Purpose:
- Verify target user existence before final recharge/retry.
Example:
```bash
```bash
curl -s"${BASE}/api/v1/admin/users/123"\
curl -s"${BASE}/api/v1/admin/users/123"\
-H"x-api-key: ${KEY}"
-H"x-api-key: ${KEY}"
```
```
### 3) Balance Adjustment (Existing API)
### 3) Balance Adjustment (existing API)
`POST /api/v1/admin/users/:id/balance`
`POST /api/v1/admin/users/:id/balance`
Purpose:
Use case: manual correction with `set` / `add` / `subtract`.
- Reuse existing admin endpoint for manual reconciliation.
- Supports `set`, `add`, `subtract`.
Request body example (`subtract`):
Request body example (`subtract`):
```json
```json
{
{
"balance":100.0,
"balance":100.0,
...
@@ -265,8 +206,6 @@ Request body example (`subtract`):
...
@@ -265,8 +206,6 @@ Request body example (`subtract`):
}
}
```
```
Example:
```bash
```bash
curl -X POST "${BASE}/api/v1/admin/users/123/balance"\
curl -X POST "${BASE}/api/v1/admin/users/123/balance"\
-H"x-api-key: ${KEY}"\
-H"x-api-key: ${KEY}"\
...
@@ -279,35 +218,24 @@ curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
...
@@ -279,35 +218,24 @@ curl -X POST "${BASE}/api/v1/admin/users/123/balance" \
}'
}'
```
```
### 4) Purchase URL Query Parameters (Iframe + New Tab)
### 4) Purchase URL query forwarding (iframe and new tab)
When Sub2API opens `purchase_subscription_url`, it appends:
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.
