Recharge, Payments, and Promotions

The central rule of the recharge page is: account credit and balance are always recorded in USD, while a payment method may collect another currency. Before creating an order, the page shows both the credited amount and actual charged amount.

Do not confuse these amounts

Amount	Meaning	Example
Recharge principal	USD amount selected by the user	USD 10.00
Credited amount	Principal after the recharge multiplier, plus a promotion bonus	USD 15.00
Charged amount	Principal and fee converted into the payment currency	HKD 78.60

The CNY toggle is for model-price and reference-price display only. It uses a cached USD/CNY rate and does not convert account balance into CNY. Order fields such as currency, payment_currency, credited_currency, fx_rate, and fx_source distinguish the charged currency from the credited USD currency.

Payment methods

Availability depends on administrator configuration, region, device, and payment-provider eligibility. The recharge page is the source of truth.

Display method	Internal type	Common charge currency	Notes
Card	stripe_card	USD	Card entry completes inside the payment page
Link	stripe_link	USD	The Link component appears only when Stripe and the browser are eligible
Alipay	stripe_alipay	HKD	A Hong Kong Stripe account defaults this local wallet to HKD
WeChat Pay	stripe_wechat_pay	HKD	A Hong Kong Stripe account defaults this local wallet to HKD
Cryptocurrency	crypto and asset-specific types	Quoted per order	The page provides the asset, network, address, and exact amount

The system may also expose direct Alipay, WeChat, aggregator, or other provider instances. A missing method commonly means the instance is disabled, the amount is outside its limits, its daily capacity is exhausted, or the current environment is ineligible.

How exchange rates work

For a USD balance with an HKD charge, QuotaAPI:

1. Fetches from the built-in live FX source and caches the result.
2. Uses the administrator's USD/HKD fallback if the live source fails.
3. Applies the configured FX markup.
4. Locks the effective rate and source into the order; later market changes do not reprice it.
5. Rounds the charged amount up to the payment currency's fraction digits without changing the credited USD principal.

Example: for a USD 1.00 recharge with a locked 7.86 rate and no additional fee, the payment is HKD 7.86 while the base credit remains USD 1.00.

If neither a live nor fallback rate is available, order creation fails instead of charging at zero or using an unknown price.

Recharge promotions

The recharge page can show eligible public promotions before an amount or payment method is selected. Paused, ended, expired, exhausted, or budget-depleted promotions disappear automatically. Coupon-only campaigns are not shown in the public banner.

Common rules include:

• Fixed bonus: add a fixed USD credit after the recharge qualifies.
• Percentage bonus: add a percentage of the recharge principal, such as 50% on USD 100.
• New-user promotion: available only when the user has no order that ever reached a paid-or-later state; a refund does not restore eligibility.
• Existing-user promotion: available only after a prior successful payment.
• Scope limits: amount, user group, payment method, plan, activity dates, and per-user use count.

Only one best eligible promotion is selected; promotions do not stack. The matcher compares actual benefit first, then campaign priority and creation time. Before order creation, a coupon preview shows validity, USD amount to pay, bonus or discount, and final credited amount.

The frontend obtains public campaigns from GET /api/v1/payment/promotions/available; its relative API path is /payment/promotions/available.

TIP

Campaign capacity is reserved when an order is created, released after cancellation, expiration, or creation failure, and consumed only after successful payment. Do not create multiple pending orders to hold the same new-user benefit.

Cryptocurrency precautions

1. Pay the exact asset, network, address, and amount shown.
2. Underpayment, late payment, or the wrong network normally requires manual review.
3. Blockchain confirmation can be slow; do not send a duplicate transfer just because the page is still waiting.
4. Keep the order number and transaction hash when opening a ticket.

Payment completed but credit is missing

1. Open the order page and inspect status instead of paying again.
2. Use the status refresh action for a still-pending order.
3. Check whether the browser blocked a payment popup or return navigation.
4. For cryptocurrency, verify the network and exact amount.
5. Open a ticket with the order number if funds were charged but fulfillment remains incomplete.

See Subscriptions, Orders, and Refunds for status and refund behavior.