sub2api/docs/PAYMENT.md

Payment System Configuration Guide

Sub2API has a built-in payment system that enables user self-service top-up without deploying a separate payment service.

---

Table of Contents

• Supported Payment Methods
• Quick Start
• System Settings
• Provider Configuration
• Provider Instance Management
• Webhook Configuration
• Payment Flow
• Migrating from Sub2ApiPay

---

Supported Payment Methods

Provider	Payment Methods	Description
EasyPay	Alipay, WeChat Pay	Third-party aggregation via EasyPay protocol
Alipay (Direct)	PC Page Pay, H5 Mobile Pay	Direct integration with Alipay Open Platform, auto-switches by device
WeChat Pay (Direct)	Native QR Code, H5 Pay	Direct integration with WeChat Pay APIv3, mobile-first H5
Stripe	Card, Alipay, WeChat Pay, Link, etc.	International payments, multi-currency support

Alipay/WeChat Pay direct and EasyPay can coexist. Direct channels connect to payment APIs directly with lower fees; EasyPay aggregates through third-party platforms with easier setup.

---

Quick Start

1. Go to Admin Dashboard → Settings → Payment Settings tab
2. Enable Payment
3. Configure basic parameters (amount range, timeout, etc.)
4. Add at least one provider instance in Provider Management
5. Users can now top up from the frontend

---

System Settings

Configure the following in Admin Dashboard Settings → Payment Settings:

Basic Settings

Setting	Description	Default
Enable Payment	Enable or disable the payment system	Off
Product Name Prefix	Prefix shown on payment page	-
Product Name Suffix	Suffix (e.g., "Credits")	-
Minimum Amount	Minimum single top-up amount	1
Maximum Amount	Maximum single top-up amount (empty = unlimited)	-
Daily Limit	Per-user daily cumulative limit (empty = unlimited)	-
Order Timeout	Order timeout in minutes (minimum 1)	5
Max Pending Orders	Maximum concurrent pending orders per user	3
Load Balance Strategy	Strategy for selecting provider instances	Least Amount

Load Balance Strategies

Strategy	Description
Round Robin	Distribute orders to instances in rotation
Least Amount	Prefer instances with the lowest daily cumulative amount

Cancel Rate Limiting

Prevents users from repeatedly creating and canceling orders:

Setting	Description
Enable Limit	Toggle
Window Mode	Sliding / Fixed window
Time Window	Window duration
Window Unit	Minutes / Hours
Max Cancels	Maximum cancellations allowed within the window

Help Information

Setting	Description
Help Image	Customer service QR code or help image (supports upload)
Help Text	Instructions displayed on the payment page

---

Provider Configuration

Each provider type requires different credentials. Select the type when adding a new provider instance in Provider Management → Add Provider.

EasyPay

Compatible with any payment service that implements the EasyPay protocol.

Parameter	Description	Required
Merchant ID (PID)	EasyPay merchant ID	Yes
Merchant Key (PKey)	EasyPay merchant secret key	Yes
API Base URL	EasyPay API base address	Yes
Notify URL	Async callback URL for payment success	Yes
Return URL	Redirect URL after payment completion	No
Alipay Channel ID	Specify Alipay channel (optional)	No
WeChat Channel ID	Specify WeChat channel (optional)	No

Alipay (Direct)

Direct integration with Alipay Open Platform. Supports PC page pay and H5 mobile pay.

Parameter	Description	Required
AppID	Alipay application AppID	Yes
Private Key	RSA2 application private key	Yes
Alipay Public Key	Alipay public key	Yes
Notify URL	Async callback URL	Yes
Return URL	Redirect URL after payment	No

WeChat Pay (Direct)

Direct integration with WeChat Pay APIv3. Supports Native QR code and H5 payment.

Parameter	Description	Required
AppID	WeChat Pay AppID	Yes
Merchant ID (MchID)	WeChat Pay merchant ID	Yes
Merchant API Private Key	Merchant API private key (PEM format)	Yes
Certificate Serial Number	Merchant certificate serial number	Yes
APIv3 Key	32-byte APIv3 key	Yes
WeChat Pay Public Key	WeChat Pay public key (PEM format)	Yes
WeChat Pay Public Key ID	WeChat Pay public key ID	Yes
Notify URL	Async callback URL	Yes

Stripe

International payment platform supporting multiple payment methods and currencies.

Parameter	Description	Required
Secret Key	Stripe secret key (sk_live_... or sk_test_...)	Yes
Publishable Key	Stripe publishable key (pk_live_... or pk_test_...)	Yes
Webhook Secret	Stripe Webhook signing secret (whsec_...)	Yes

---

Provider Instance Management

You can create multiple instances of the same provider type for load balancing and risk control:

• Multi-instance load balancing — Distribute orders via round-robin or least-amount strategy
• Independent limits — Each instance can have its own min/max amount and daily limit
• Independent toggle — Enable/disable individual instances without affecting others
• Refund control — Enable or disable refunds per instance
• Payment methods — Each instance can support a subset of payment methods
• Ordering — Drag to reorder instances

Instance Limit Configuration

Each instance supports these limits:

Limit	Description
Minimum Amount	Minimum order amount accepted by this instance
Maximum Amount	Maximum order amount accepted by this instance
Daily Limit	Daily cumulative transaction limit for this instance

During load balancing, instances that exceed their limits are automatically skipped.

---

Webhook Configuration

Payment callbacks are essential for the payment system to work correctly.

Callback URL Format

Provider	Callback URL
EasyPay	https://your-domain.com/api/v1/payment/easypay/notify
Alipay (Direct)	https://your-domain.com/api/v1/payment/alipay/notify
WeChat Pay (Direct)	https://your-domain.com/api/v1/payment/wxpay/notify
Stripe	https://your-domain.com/api/v1/payment/stripe/webhook

Replace your-domain.com with your actual domain.

Stripe Webhook Setup

1. Log in to Stripe Dashboard
2. Go to Developers → Webhooks
3. Add an endpoint with the callback URL
4. Subscribe to events: payment_intent.succeeded, payment_intent.payment_failed
5. Copy the generated Webhook Secret (whsec_...) to your provider configuration

Important Notes

• Callback URLs must use HTTPS (required by Stripe, strongly recommended for others)
• Ensure your firewall allows callback requests from payment platforms
• The system automatically verifies callback signatures to prevent forgery
• Balance top-up is processed automatically upon successful payment — no manual intervention needed

---

Payment Flow

User selects amount and payment method
       │
       ▼
  Create Order (PENDING)
  ├─ Validate amount range, pending order count, daily limit
  ├─ Load balance to select provider instance
  └─ Call provider to get payment info
       │
       ▼
  User completes payment
  ├─ EasyPay     → QR code / H5 redirect
  ├─ Alipay      → PC page pay / H5 mobile pay
  ├─ WeChat Pay  → Native QR / H5 pay
  └─ Stripe      → Payment Element (card/Alipay/WeChat/etc.)
       │
       ▼
  Webhook callback verified → Order PAID
       │
       ▼
  Auto top-up to user balance → Order COMPLETED

Order Status Reference

Status	Description
PENDING	Waiting for user to complete payment
PAID	Payment confirmed, awaiting balance credit
COMPLETED	Balance credited successfully
EXPIRED	Timed out without payment
CANCELLED	Cancelled by user
FAILED	Balance credit failed, admin can retry
REFUND_REQUESTED	Refund requested
REFUNDING	Refund in progress
REFUNDED	Refund completed

Timeout and Fallback

• Before marking an order as expired, the background job queries the upstream payment status first
• If the user has actually paid but the callback was delayed, the system will reconcile automatically
• The background job runs every 60 seconds to check for timed-out orders

---

Migrating from Sub2ApiPay

If you previously used Sub2ApiPay as an external payment system, you can migrate to the built-in payment system:

Key Differences

Aspect	Sub2ApiPay	Built-in Payment
Deployment	Separate service (Next.js + PostgreSQL)	Built into Sub2API, no extra deployment
Payment Methods	EasyPay, Alipay, WeChat, Stripe	Same
Configuration	Environment variables + separate admin UI	Unified in Sub2API admin dashboard
Top-up Integration	Via Admin API callback	Internal processing, more reliable
Subscription Plans	Supported	Not yet (planned)
Order Management	Separate admin interface	Integrated in Sub2API admin dashboard

Migration Steps

1. Enable payment in Sub2API admin dashboard and configure providers (use the same payment credentials)
2. Update webhook callback URLs to Sub2API's callback endpoints
3. Verify that new orders are processed correctly via built-in payment
4. Decommission the Sub2ApiPay service

Note

: Historical order data from Sub2ApiPay will not be automatically migrated. Keep Sub2ApiPay running for a while to access historical records.