Game Top-Up API for Resellers
Short Answer
A game top-up API lets resellers send in-game currency (UC, Diamonds, Robux, Crystals) directly to a player's game account by submitting their player ID and the top-up amount. Unlike a gift card API that delivers a code, a top-up API sends credit to the account without generating a redeemable code. This changes the integration requirements: player ID validation is mandatory, region matching is critical, and there is no code for the customer to misuse or resell. The key API features for top-up resellers are: player ID validation, region specification, order creation, delivery status and reconciliation.
Definition: A game top-up API is a B2B interface that allows resellers to fund a player's in-game account with virtual currency by submitting a player ID and selecting a top-up package — without generating a redeemable code. Delivery is direct to the game account.
Key takeaway: Top-up APIs have a lower code fraud risk than gift card APIs because no redeemable code is generated. But they have stricter input requirements: a wrong player ID or mismatched region means the credit goes to the wrong account or fails entirely. Player ID validation is not optional.
Who This Guide Is For
This guide is for:
- Resellers who sell in-game currency (PUBG UC, Roblox Robux, Mobile Legends Diamonds, Genshin Crystals, etc.) and want to automate delivery
- Online store owners adding game top-ups to their product catalog
- Telegram bot developers building automated top-up delivery
- Developers integrating a top-up supplier into a store or marketplace backend
What a Game Top-Up Is
A game top-up is a direct addition of in-game currency to a player's account. Unlike a gift card, which generates a code the player redeems, a top-up credits the account without any intermediate code.
Examples:
- 600 UC added to a PUBG Mobile account (identified by a player ID)
- 800 Robux added to a Roblox account (identified by username or user ID)
- 500 Diamonds added to a Mobile Legends account (identified by player ID + server ID)
- 980 Genesis Crystals added to a Genshin Impact account (identified by UID + server region)
Top-Up vs. Gift Card: What Changes for Resellers
| Factor | Gift Card API | Top-Up API |
|---|---|---|
| What is delivered | A redeemable code | Credit directly to game account |
| Customer input required | None (code is self-contained) | Player ID (+ server ID for some games) |
| Region sensitivity | Region on the card must match account region | Player's game region must be specified |
| Refund risk | Codes can be misused before reporting | Account credit is non-reversible |
| Integration complexity | Lower | Higher (player ID validation) |
| Resale risk | Code can be screenshot and sold | No code; no resale risk |
How a Top-Up API Works
Core API Workflow
1. Customer enters player ID (and server if required)
2. Your store calls player ID validation endpoint
3. API confirms player ID exists and returns account name
4. Customer confirms and pays
5. Your store calls order creation endpoint with validated player ID
6. API sends currency to the game account
7. API returns delivery confirmation
8. Your store shows confirmation to customer
Player ID Validation
This is the step most integrations skip and regret. Player ID validation checks that the ID the customer entered is:
- A real account that exists
- In the correct game and server
- Eligible to receive the top-up (some accounts have restrictions)
Why it matters: If you skip validation and the customer mistyped their player ID, the top-up goes to the wrong account (or fails). The customer opens a dispute. Most suppliers treat a delivered top-up as non-refundable because the game account received the credit.
The validation endpoint typically returns the account's display name. Show this to the customer before payment: "Top-up will be sent to: [DisplayName] — is this correct?"
Region Specification
Many games partition their player base into regional servers. A PUBG Mobile player on the Asia server has a different account space than one on the America server, even with the same player ID format.
Games that require server/region specification:
- Mobile Legends: Bang Bang (requires server ID)
- Genshin Impact (requires server: Asia, America, Europe, TW/HK/MO)
- Honkai: Star Rail (requires server)
- Arena of Valor (server-dependent)
Games where player ID is globally unique:
- PUBG Mobile (player ID is globally unique)
- Roblox (username or user ID is globally unique)
- Free Fire (player ID is globally unique)
Core API Features for Top-Up Resellers
| API Feature | Purpose | Required For |
|---|---|---|
| Player ID validation | Confirm player exists before charging customer | All top-up products |
| Package list per game | List available top-up amounts for each game | Catalog display |
| Order creation | Submit top-up order with player ID and package | Fulfillment |
| Order status | Check delivery confirmation | Customer service |
| Balance API | Check reseller account balance | Prevent failed orders |
| Webhooks | Receive push when order completes | High-volume automation |
| Reconciliation | Export order history for finance | Accounting, audit |
Integration: What Your Store Needs
Product Page Requirements
Each top-up product page needs:
- A player ID input field (mandatory)
- A server/region selector (where required by the game)
- A validation button or real-time validation trigger
- Display of the resolved account name before payment
- Clear confirmation step showing account name + amount
Checkout Flow for Top-Ups
Step 1: Customer selects game and top-up amount
Step 2: Customer enters player ID (and server if needed)
Step 3: Your store calls validation endpoint
→ Show account display name to customer
→ If validation fails: show error, do not proceed
Step 4: Customer confirms and pays
Step 5: Your store calls order creation
Step 6: Display delivery confirmation with timestamp
Error Handling
| Error Scenario | Cause | What to Show Customer |
|---|---|---|
| Invalid player ID | Typo or non-existent account | "Player ID not found. Check your ID and try again." |
| Wrong server | Correct ID, wrong server selected | "ID not found on this server. Check your server." |
| Account restricted | Game account is banned or restricted | "This account cannot receive top-ups." |
| Insufficient balance | Your reseller balance too low | Order should not have been placed; add balance monitoring |
| Delivery failed | Game server error | Retry or contact support; do not charge customer |
Handling Refunds in Top-Up Reselling
Top-up transactions are generally non-reversible once the game account receives the credit. This changes the refund model compared to gift cards:
Gift cards: If a code was not used, a supplier may accept a refund claim within a defined window.
Top-ups: Once credited to the account, the game platform controls the currency. The supplier typically cannot reverse a delivered top-up. This means:
- Refund risk is very low for you as a reseller — delivered credit is non-reversible
- Customer responsibility is high — they must provide the correct player ID
- Your terms of service must clearly state that top-ups are non-refundable after delivery
- Player ID validation before payment is the primary risk control
Margin Calculation for Top-Up Resellers
The margin formula is the same as for gift cards. The practical difference is that the refund reserve can be set lower for top-ups because:
- No code exists for a customer to misuse
- A delivered top-up is non-reversible from the supplier's side
- The main dispute scenario (wrong account) is prevented by ID validation
Illustrative example (example only; not FoxReload pricing):
| Item | Amount |
|---|---|
| Retail price (600 UC package) | $9.99 |
| Wholesale cost (12% off retail) | $8.79 |
| Payment processing fee (2%) | $0.20 |
| FX cost (0.5%) | $0.04 |
| Refund reserve (0.2%) | $0.02 |
| Net profit | $0.94 |
| Net margin | 9.4% |
Lower refund reserve compared to gift cards is the main margin benefit of top-up reselling.
Common Mistakes in Top-Up API Integration
Skipping player ID validation — the most common mistake. Always validate before charging.
Not showing the resolved account name — customers mistype IDs. Showing the name is the last line of defense.
Not handling server-required games — for Mobile Legends and Genshin, a missing server ID causes delivery failure.
Treating a failed top-up as delivered — if the API returns a failure status, do not mark the order as complete and do not charge the customer.
Not monitoring balance — a zero balance causes all orders to fail; set alerts well above your expected order size.
Not explaining non-refundability upfront — state clearly before payment that top-ups are non-refundable once delivered. This reduces disputes.
Combining top-up and gift card logic — top-up orders and gift card orders have different customer inputs, validation steps and refund policies. Handle them separately in your codebase.
Integration Checklist
- Identify which games you will offer (each has different player ID format)
- Confirm which games require server/region selection
- Implement player ID validation endpoint per game
- Build player ID input UI with server selector where needed
- Display validated account name before payment
- Implement order creation with error handling for each failure mode
- Implement order status polling for non-instant delivery
- Set up webhooks for delivery confirmation
- Set up balance monitoring with alerts
- Write customer-facing terms: top-ups non-refundable after delivery
- Test each game's ID format in sandbox (different length, format, prefix)
- Load test at expected peak order volume
- Set up reconciliation export for finance team