A game top-up API lets your storefront credit in-game currency straight to a player’s account: you read the package catalogue, validate the player ID, place the order with the validation reference, and track it to a confirmed credit. Compared with a gift card API, there is no code to deliver or store, but every order cannot be reversed by the seller once it lands on an account.
The product itself, what UID recharge is and why many mobile publishers use it, is covered in what direct top-up is. This article is for the team wiring it up: the call sequence, the data you need from the catalogue, and the failure states that are specific to top-ups.
The call sequence
A typical top-up integration uses four calls. Endpoint names below are illustrative.
- Catalogue.
GET /catalogue?delivery_type=topup&game=example-gamereturns the packages for each game and region, with the inputs each one requires. - Validate.
POST /topup/validatewith the player ID (and server where needed) returns the account nickname and a short-lived validation reference. - Order.
POST /orderswith the package ID, the validation reference and an idempotency key creates the top-up. - Status. A webhook or
GET /orders/{id}reports pending, completed or failed, with the game-side transaction reference on success.
{
"package_id": "pkg_example_660",
"validation_ref": "val_3c9e1",
"idempotency_key": "ord-2026-10-01-000123",
"customer_reference": "cart-88412"
}Steps two and three are the ones that differ from a code integration. Everything else, idempotent submission, status tracking, reconciliation, follows the same discipline as the gift card API integration guide.
What the catalogue must tell you
Top-up catalogues are messier than code catalogues, because each game defines its own currency, packages and account model. Check that every package entry carries:
- Game and region. Packages and prices are regional, and an account registered in one region usually cannot receive another region’s package.
- Currency amount. Packages are sold in game units (diamonds, UC, gems), often with bonus units on top. Show both exactly as the game does.
- Required inputs. Player ID only, or player ID plus server or zone. This list should drive your checkout form, so a new title does not need new code.
- Input format hints. Expected length or pattern of the ID, so you can catch obvious typos before calling validation at all.
Validation is a separate call, with its own lifetime
The validation step resolves the ID to a nickname, the buyer confirms it, and only then do you take payment. Why the confirmation must block, and how server selection changes the answer, is covered in player ID validation for top-ups.
For the integration, two details matter. The validation reference expires, usually within minutes, so validate close to payment and re-validate if the cart sat idle. And validation answers “does this account exist”, not “can this order succeed”: an account can pass validation and still be rejected at order time for reasons below.
Code API vs top-up API
| Aspect | Gift card code API | Game top-up API |
|---|---|---|
| What you receive | A code to deliver to the buyer | A confirmation that the account was credited |
| Pre-order step | Price and stock check | Player ID validation plus price and stock check |
| Custody risk | High: codes are bearer value | Low: no code exists |
| Wrong-recipient risk | Medium: a mis-sent code can be redeemed by whoever receives it | High: the seller cannot recall the credit |
| Typical completion | Seconds | Seconds to minutes |
| Re-delivery | Re-send the code | Not applicable; show the confirmation |
| Proof for disputes | Delivery log | Confirmed nickname and game transaction ID |
Failure states specific to top-ups
Beyond the usual errors in the order failure field guide, top-ups add a few of their own. Treat them as handled outcomes with clear messages:
- Account restricted. The account exists but cannot receive purchases, for example because it is banned or locked. Not retryable; tell the buyer.
- Region mismatch. The package region does not match the account’s region. Offer the matching regional package if you carry it.
- Game maintenance. The publisher’s recharge service is temporarily down. Orders may queue or fail; either way, do not resubmit under a new key.
- Purchase limit reached. Some games cap purchases of certain packages per account or per period. Not retryable for that package.
- Unknown state. A timeout after submission. As with codes, look the order up by idempotency key before doing anything else.
Keep the right record
Your receipt and your order log should hold the player ID, server, the confirmed nickname, the validation reference and the game-side transaction ID returned on completion. When a buyer says the currency never arrived, that set of fields is what lets you, the provider and the publisher trace it in minutes rather than days.
Giftoro carries direct top-ups alongside codes through the same integration; the gift card and top-up API overview explains the scope, and a sandbox key is available on request.
Frequently asked questions
What is a game top-up API?
It is an API that credits in-game currency directly to a player’s account using their player ID, instead of issuing a code. A storefront uses it to list packages, validate the ID, place the order and confirm the credit, typically within seconds to minutes.
Can I use the same integration for codes and top-ups?
Usually yes, if the provider exposes both through one API. The catalogue marks each product’s delivery type, and your checkout adds the validation step only for top-up products. Ordering, status tracking and reconciliation stay shared.
Is it safe to retry a failed top-up order?
Only through idempotency. Resubmit with the same idempotency key, or look the order up by that key first. A new key on a timed-out order risks crediting the account twice, and the seller has no way to reverse the extra credit.
Why did an order fail when the player ID validated correctly?
Validation confirms the account exists; it does not guarantee the order succeeds. The account may be restricted, registered in another region, or at a purchase limit, or the game’s recharge service may be in maintenance. Show the specific reason returned by the API.
What should I show the buyer after a successful top-up?
The game, package, player ID, confirmed nickname and the transaction reference. Most games credit the balance immediately, but some only show it after the player restarts the client, so a short note to that effect saves support tickets.