Web Payment — Expub 4-API Flow

Applies to	Exclusive/Direct-publishing (expub) games
Endpoints	getUserList_url, checkUser_url, createOrder_url, exchange_url
Signature	MD5, Signature header, timestamp in seconds
Errors	HTTP status codes

Expub games, not a deprecated contract

This 4-API flow is the current, correct web payment contract for expub (Exclusive/Direct-publishing) games — it is not being phased out and isn't something an expub title needs to migrate away from. Co-publishing (co-pub) games use a different, separate contract instead — Web Payment — Standard — because that publishing model has no Alogame-linked account to fetch a character list from. Pick the page that matches your game's publishing model, not "newest vs oldest".

An expub game also needs Mobile IAP for its in-app purchases — the two are implemented together, not one instead of the other, each covering a different purchase surface (web top-up vs in-app store).

On a PHP backend? Don't hand-implement this contract — install Web Payment — PHP SDK instead, which covers both this flow and Expub's shared Mobile IAP.

Flow

The player reaches this flow only after logging into their Alogame account — direct-publish games link a player's Alogame account to their in-game character(s) ahead of time, which is what lets getUserList_url return a character list for a known userId with no UID typed by the player. This is the main difference from co-pub's Web Payment — Standard, where the player types a UID with no Alogame account/login involved.

The diagram below shows every step in the top-up flow. Steps highlighted in green are implemented by your game server; all other steps are handled by Alogame.

Step-by-step breakdown

#	Who acts	What happens	Your responsibility
1–2	User + Alogame SDK	User opens top-up screen; SDK requests character list	—
3	Game Server	Alogame calls your registered getUserList_url with the Alogame userId	Return all characters linked to this user
4–6	Alogame SDK + User	Characters shown to user; user picks character, package, and payment method	—
7	Game Server	Alogame calls your checkUser_url to confirm the selected UID still exists	Return 200 if UID valid, 404 if not
8	Alogame Backend	Alogame generates a unique order_id internally	—
9	Game Server	Alogame calls your createOrder_url with order_id, uid, and productId	Create a local order record; return your own order_code
10–12	Alogame + User + Payment Provider	User sees payment UI; user pays; payment provider notifies Alogame via IPN	—
13	Alogame Backend	Alogame verifies the IPN and marks the Alogame order as paid	—
14	Game Server	Alogame calls your exchange_url with the order_code you returned in step 9	Grant the item to the player; respond 200
15	Alogame SDK	User receives success notification	—

What you need to build

Config key	Triggered at step	Purpose
getUserList_url	Step 3	Return character list for a user
checkUser_url	Step 7	Confirm a UID is still valid
createOrder_url	Step 9	Create local order; return your order_code
exchange_url	Step 14	Grant item after payment is confirmed

Your game's mobile app also needs Mobile IAP for in-app purchases — it reuses these same createOrder_url and exchange_url, registered once and shared by both flows.

Critical: idempotency for steps 9 and 14

Alogame may retry on network failure. Your server must deduplicate:

• Step 9: if order_id already exists → return 409 ORDER_ALREADY_EXISTS (include original order_code in body)
• Step 14: if order_code already delivered → return 409 PAYMENT_ALREADY_PROCESSED (do not re-grant)

Endpoint Registration

Before Alogame can call your server, submit your endpoint URLs to your Alogame Operations Manager. Each URL is a complete static string — Alogame stores it as-is and calls it directly. You must provide separate URLs for production and dev/staging.

Environment	Notes
Production	Must use HTTPS with a valid TLS certificate
Dev / Staging	HTTP accepted; used for integration testing only

Submit 4 URLs per environment:

# Production
getUserList_url: https://api.yourgame.com/<your-path>
checkUser_url:  https://api.yourgame.com/<your-path>
createOrder_url: https://api.yourgame.com/<your-path>
exchange_url:   https://api.yourgame.com/<your-path>

# Dev / Staging
getUserList_url: http://<dev-host>/<your-path>
checkUser_url:  http://<dev-host>/<your-path>
createOrder_url: http://<dev-host>/<your-path>
exchange_url:   http://<dev-host>/<your-path>

Alogame routes to the correct environment without any SDK or client config change.

Each URL is registered independently, so the four paths do not need to share a prefix or follow any naming convention — use whatever your server already exposes.

Authentication

Requests carry a Signature header computed with MD5 over a sorted query string. The algorithm and verification samples are on the Authentication page.

---

API 1 — Get Character List

Called when the user opens the Alogame top-up screen.

Method: POST
Path: full static URL as registered with Alogame Operations

Request body

Field	Type	Description
userId	string (UUID)	Alogame user ID
ext_info	string	Context forwarded from the SDK
timestamp	integer	Unix timestamp (seconds)

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "ext_info": "{}",
  "timestamp": 1678886400
}

Headers

Signature: <computed_hash>

Response — 200 OK

{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "uids": [
    {
      "uid": "char_001",
      "server": "Server 1",
      "characterName": "DragonSlayer"
    },
    {
      "uid": "char_002",
      "server": "Server 2",
      "characterName": "IronMage"
    }
  ]
}

Error responses

Status	Code	Meaning
401	SIGNATURE_INVALID	Signature check failed
404	NOT_FOUND	userId does not exist
400	INVALID_FORMAT	userId is not a valid UUID

---

API 2 — Check UID

Called after the user selects a character, before order creation. Confirms the UID still exists.

Method: POST
Path: full static URL as registered with Alogame Operations

Request body

Field	Type	Description
uid	string	Character UID from API 1 response
ext_info	string	Context forwarded from the SDK
timestamp	integer	Unix timestamp (seconds)

{
  "uid": "char_001",
  "ext_info": "{}",
  "timestamp": 1678886400
}

Response — 200 OK

{
  "characterName": "DragonSlayer",
  "server": "Server 1"
}

Error responses

Status	Code	Meaning
401	SIGNATURE_INVALID	Signature check failed
404	UID_NOT_FOUND	UID does not exist

---

API 3 — Create Order

Called after UID is confirmed. Your server creates a local order record and returns a partner order code.

Method: POST
Path: full static URL as registered with Alogame Operations

Request body

Field	Type	Description
order_id	string	Alogame order ID
uid	string	Selected character UID
productId	string	Your own product ID, exactly as you submitted it to Alogame
ext_info	string	Context forwarded from the SDK
timestamp	integer	Unix timestamp (seconds)

{
  "order_id": "alo_ord_1a2b3c4d",
  "uid": "char_001",
  "productId": "pack_500_gold",
  "ext_info": "{}",
  "timestamp": 1678886400
}

Response — 201 Created

{
  "status": "success",
  "order_code": "PARTNER-ORD-20230315-001"
}

Error responses

Status	Code	Meaning
401	SIGNATURE_INVALID	Signature check failed
409	ORDER_ALREADY_EXISTS	Duplicate order_id — return your existing order_code
404	PRODUCT_NOT_FOUND	Product does not exist
404	UID_NOT_FOUND	UID does not exist

Handle 409 as success

If Alogame retries and receives 409 ORDER_ALREADY_EXISTS, it will proceed using the original order_code. Return the original order_code in the 409 body if possible.

---

API 4 — Deliver Item (Payment Received)

Called after payment is fully confirmed by the payment provider. Grant the purchased item to the player.

Method: POST
Path: full static URL as registered with Alogame Operations

Request body

Field	Type	Description
order_code	string	Partner order code returned from API 3
ext_info	string	Context forwarded from the SDK
timestamp	integer	Unix timestamp (seconds)

{
  "order_code": "PARTNER-ORD-20230315-001",
  "ext_info": "{}",
  "timestamp": 1678886400
}

Response — 200 OK

{
  "processingStatus": "completed"
}

Error responses

Status	Code	Meaning
401	SIGNATURE_INVALID	Signature check failed
404	ORDER_CODE_NOT_FOUND	order_code does not exist
409	PAYMENT_ALREADY_PROCESSED	Already delivered — safe for Alogame to ignore

Idempotency required

Alogame may retry this call on timeout or network failure. Your server must deduplicate on order_code and return 409 PAYMENT_ALREADY_PROCESSED for duplicates without re-granting the item.

---

Implementation checklist

• Submitted all 4 endpoint URLs to Alogame Operations
• Production endpoints use HTTPS with a valid TLS certificate
• API 1 (getUserList_url): returns character list for a valid userId
• API 2 (checkUser_url): confirms UID exists before order creation
• API 3 (createOrder_url): creates order record; returns 409 (not 500) for duplicate order_id
• API 4 (exchange_url): grants item; returns 409 (not 500) for duplicate order_code
• All APIs: verify Signature header; reject if |now − timestamp| > 600s
• Delivery logged with order_code, uid, productId for CS lookup