In-Game Top-Up (Embedded Web Payment)
| Applies to | Games that want the top-up flow embedded in-game instead of opening the web portal |
| Builds on | Your existing Web Payment — Standard or Expub integration — create_order/payment_notify are unchanged; check_uid/server_list stay as-is and mostly stop mattering once you're passing uid/server_id directly (see below) |
| New server work | None, if using the SDK entry mechanism. Using the signed deep link instead means building that one payload server-side — no new endpoint, no change to create_order/payment_notify. |
This page is about the web-payment top-up flow rendered inside the game client (character UID → package → payment provider), the same flow the web portal uses. It has nothing to do with Apple/Google billing — for purchases through StoreKit or Google Play Billing, see Mobile IAP instead. If your title uses both, you implement both independently.
There is no separate contract
"In-game" vs "web portal" is a UI decision on Alogame's side, not a different API for your server. Whether the player reaches checkout by opening alogame.vn in a browser or by tapping "Top up" inside your game client, Alogame calls the exact same check_uid / create_order / payment_notify (or the 4-API expub equivalent) on your server, with the exact same signature scheme.
If your game already implements Web Payment — Standard or Web Payment — Expub, you do not need to change anything on the check_uid/create_order/payment_notify side to support in-game top-up. What's left is choosing how the top-up page opens, and the operational step of turning the feature on:
- Confirm with your Alogame Operations Manager that in-game top-up is enabled for your title.
- Pick an entry mechanism — see below.
Everything below the entry mechanism is optional — only relevant if your game also needs one of the two extensions in-game top-up commonly comes with.
Entry mechanism: SDK call or signed deep link
There are two ways a player ends up on the embedded top-up page. Pick one; don't mix both for the same title.
| SDK call | Signed deep link | |
|---|---|---|
| Who opens the page | The Alogame SDK, from a native call your game client makes | Your own game client, opening a URL your backend builds and signs |
| New work on your side | Integrate the SDK's embedded top-up entry point (Android, iOS, Bridge/Cocos-Egret) | Build and sign the URL below — no SDK dependency |
| Use when | Your title already integrates Alogame SDK v2 | Your client can open a webview but doesn't (yet) carry the native SDK |
Signed deep link
Your backend builds this URL and hands it to your game client to open in a webview:
https://nap.alogame.vn/ingame/{slug}?uid=...&product_id=...&deeplink_ts=...&deeplink_sig=...
| Param | Required? | Notes |
|---|---|---|
slug | always | your game's slug on Alogame, in the path — ask Alogame Operations if you don't have it |
uid | always | same character/account identifier your check_uid contract uses |
product_id | always | the package ID being topped up |
deeplink_ts | always | Unix milliseconds, generated right before opening the link |
deeplink_sig | always | see signature algorithm |
order_code | optional | include only if your flow tracks its own order code |
server_id | optional | multi-server titles — see extension below |
return_url | optional | where the player lands after payment completes |
deeplink_sig is computed with the same secret_key issued for your check_uid/create_order contract — see Authentication — HMAC-SHA256, sorted query string for the exact algorithm, a worked example, and Node.js/PHP samples. Build the URL and its signature server-side only — never embed secret_key in a game client, since anyone who extracts it could open a top-up page as any UID.
Your backend already knows which player and which server this is before it builds the link — that's why uid (and server_id, if you have servers) are in the payload. The top-up page doesn't ask the player to enter a UID or pick a server; it goes straight to showing the package(s) that match what you sent. Alogame may still call your check_uid in the background to confirm the character is real before create_order — you don't build anything new for that, it's the same check_uid your base contract already implements.
This is also why server_list is not needed for this entry mechanism — that endpoint exists to render an interactive server picker, and with the deep link there's nothing to pick.
The two things that actually matter for this entry mechanism are building this payload and making sure your existing create_order / payment_notify keep working unchanged — everything else on this page is either automatic or inherited from your base integration.
Extension: multi-server games
If you're using the signed deep link, you already send server_id in the payload — skip this section, there's no picker to register. This extension is for the interactive flow, where the player enters a UID and picks a server on the page itself.
If your players belong to a specific server (not just a global UID), tell your Alogame Operations Manager — two things change:
1. check_uid and create_order gain a server_id field, alongside the fields already documented for your contract:
{
"uid": "100002078",
"server_id": "s2"
}
server_id is whatever string you use to identify a server internally. Alogame passes it back unchanged from what the player selected.
2. You register one extra endpoint, server_list, so Alogame can show a server picker before the player enters their UID:
Method: POST
Reference path: /server_list
Request body — no fields beyond signature-related ones (empty object, or {"game_id": "..."} for a multi-platform game):
{}
Response — success
The shape follows your contract's normal envelope:
{
"errcode": 0,
"msg": "success",
"data": [
{ "serverId": "s1", "name": "Server 1" },
{ "serverId": "s2", "name": "Server 2" }
]
}
[
{ "serverId": "s1", "name": "Server 1" },
{ "serverId": "s2", "name": "Server 2" }
]
Only serverId and name are read. A slow or failing server_list call degrades to an empty picker rather than breaking the page — Alogame gives it a short timeout (3s) specifically because it is fetched while the game page renders, before the player has done anything.
Web Payment — Standard notes that UIDs must be unique across all servers because there is no server picker on that contract. Registering server_list is what lifts that limitation — once it's in place, check_uid/create_order disambiguate by server_id and your UIDs only need to be unique within a server.
Extension: multi-platform games
If your title runs iOS and Android as two separate games on your backend (two different game IDs, possibly even two different accounts), tell your Alogame Operations Manager both IDs. Every request — check_uid, create_order, payment_notify, and server_list if you have it — then carries a game_id field telling you which store the player is on:
{
"uid": "100002078",
"game_id": "268"
}
game_id is whichever of the two IDs you gave Alogame for that platform — not an Alogame-internal ID. Route the request to the matching backend/game account accordingly.
If a request arrives without a platform your title has provisioned a game_id for, treat it the same as any other misconfigured request — Alogame will not send check_uid/create_order for a platform it doesn't have a game_id on file for.
Existing integrations
A small number of titles already had in-game top-up enabled before this page's signed deep link existed. Their entry URL uses a bespoke, encrypted payload agreed one-on-one with Alogame at the time — do not copy that scheme; it predates this page and isn't documented here for new integrations to reference. A new title needing a deep-link entry point should use the signed deep link above instead. The check_uid/create_order/payment_notify contract itself was never bespoke and is unaffected either way — see Standard or Expub.
Implementation checklist
- Already implements Web Payment — Standard or Web Payment — Expub — no new server work otherwise
- Confirmed with Alogame Operations that in-game top-up is enabled for this title
- Chose an entry mechanism: SDK call, or signed deep link — not both
- SDK call: game client calls the SDK's embedded top-up entry point
- Signed deep link: backend builds and signs the payload server-side (the part that actually matters here);
secret_keynever ships in a client build;create_order/payment_notifyuntouched
- Multi-server titles using the SDK call or web portal: registered
server_list;check_uid/create_orderhandleserver_id - Multi-server titles using the signed deep link:
server_idincluded in the payload — noserver_listneeded - Multi-platform titles: gave Alogame both
game_idvalues; every endpoint routes on the incominggame_id