UTD Games

1) Your app opens the game's Launch URL in a WebView and appends the player's identity: &uid=<player id>&token=<a session token YOUR backend issued for that player>. 2) The game engine calls your get-user-info callback with that same uid + token — you MUST verify the token really belongs to that uid (mismatch → errorCode 10003); the signature only proves the call came from the games platform, the token is what proves the player. 3) Every bet/win during play calls your change-balance callback. coin values are in YOUR app's coin currency (the coin price you set at submission, e.g. 1 USD = 13,000 coins). In get-user-info, nickname/avatar personalize the game UI; vipLevel and water can be 0 if you don't use them.

Called once when a player opens a game. Verify sign = md5(gameId + uid + token + roomId + APP_KEY) — concatenated values, no separators, compared case-insensitively — then return the player's profile and current balance. uid and coin are REQUIRED inside data. Bad signature → errorCode 10004. Unknown player or uid/token mismatch → 10003. Player blocked or games intentionally disabled on your side → 30001.

Retourne: { errorCode: 0, errorMsg: "success", data: { uid, nickname, avatar, coin, vipLevel, water } } — HTTP 200 always. data.coin is the player's current balance (integer).

Called on every bet and win. type=1 → deduct coin (bet), type=2 → add coin (win). Verify sign = md5(orderId + gameId + roundId + uid + coin + type + rewardType + token + winId + roomId + APP_KEY). Apply the change, then read the wallet AGAIN and return the NEW balance — returning the old unchanged balance is the #1 activation rejection. Insufficient balance on a bet → errorCode 4004 and move no money. Must be idempotent by orderId: the same orderId arriving twice moves money once and returns the current balance with errorCode 0. coin=0 is a valid no-op (used by the dashboard self-test).

Retourne: { errorCode: 0, errorMsg: "success", data: { coins: <NEW balance>, coin: <NEW balance> } } — HTTP 200 always. data.coins MUST reflect the balance AFTER the debit/credit.

Re-settles a reward the platform believes was lost (rare). Signature has NO type and NO token: sign = md5(orderId + gameId + roundId + uid + coin + rewardType + winId + roomId + APP_KEY). CRITICAL: share ONE idempotency key with change-balance, scoped to the orderId. If that orderId was already settled, return the current balance with errorCode 0 and move NO money — a separate per-endpoint key double-credits (mints coins).

Retourne: { errorCode: 0, errorMsg: "success", data: { coin: <NEW balance> } } — HTTP 200 always. Returns the balance after the credit (or the current balance on an idempotent replay).

0 success · 4004 insufficient coins on a bet · 4005 missing/invalid parameter or a REAL backend failure ONLY (platform monitoring alerts on 4005 — never use it for intentional stops) · 10003 user not found / uid-token mismatch · 10004 signature verification failed · 30001 intentional block (player banned, or games disabled on your side). Every response is HTTP 200 with the {errorCode, errorMsg, data} envelope; error responses use data: [].

Returns whether games are enabled for the account. Requires an API token carrying the games:launch-flag ability (a session token also works for owner testing). Cache the result briefly server-side; never expose the token to a client app.

Retourne: { games_enabled: boolean } — games_enabled is true when the games wallet has a positive balance, false when gated.

Mints a new API token scoped to the games:launch-flag ability. The plaintext secret is returned once and never again — store it securely. Fails with 422 token_limit_reached at 10 active tokens.

Retourne: { token: { id, name, last_used_at, created_at }, secret: string } — secret is the plaintext bearer, shown only in this response (HTTP 201).

Lists your active games API tokens (masked — no secrets). Only games tokens are listed; your browser session token is never included.

Retourne: { tokens: Array<{ id, name, last_used_at, created_at }> } — Metadata only; the secret is never re-exposed after creation.

Revokes (permanently deletes) one of your games API tokens by id. Returns 404 if the id is not one of your games tokens.

Retourne: { ok: true } — Revocation is immediate and irreversible.

Returns your signing key (app_key) BEFORE any project exists, so you can implement signature verification and test it. The key is stable per account — calling twice returns the same key, and the project you later submit keeps this same key after activation, so nothing you built breaks.

Retourne: { app_key: string } — Your APP_KEY — the shared secret used in every callback signature.

Runs the full integration self-test against your backend before a project exists: UTD sends genuinely signed payloads (with your draft app_key) to your three callbacks and validates every response against the exact contract above — envelope, errorCode 0, balance fields, forged-signature and foreign-token rejection. It then proves the balance actually MOVES: a small credit → replay of the same orderId (must be a no-op, no coin minting) → an equal debit that restores the balance — all net-zero on your test account. This catches a backend that returns 'success' with an unchanged balance (the #1 activation rejection). A passing test unlocks project submission for the exact (callback_base_url, test_uid, test_token) you tested; changing any of them invalidates the pass and you must re-test. Rate-limited to 6 calls per minute.

Retourne: { ok: boolean, checks: Array<{ name, url, ok, http_status, error, response }>, error_codes_contract: string } — One check per callback with the exact failure reason when a response doesn't match the contract. ok: true = you can submit.

Submits a new games project for review from your dashboard session. Requires a verified phone on the account, and a passing draft callback test matching the submitted callback_base_url + test_uid + test_token exactly — otherwise 422 {"message":"callback_test_required"}. The request is multipart: all fields go JSON-encoded inside a single "payload" part, plus screenshots[] file parts. The project starts pending; the UTD team provisions it with the provider and approves it (status becomes active). Provider secrets are never exposed to your app.

Retourne: { project: { id, name, status, provider_app_id } } — The created project in pending status, awaiting UTD review. 422 callback_test_required = run the draft callback test first with these exact values.

Self-test for your three game callbacks (get-user-info / change-balance / make-up-orders). UTD sends genuinely signed payloads to your callback base URL using the project's test account. Beyond the contract checks (envelope, errorCode 0, forged-signature and foreign-token rejection), it proves the balance actually moves: a small credit → replay of the same orderId (must be a no-op — no coin minting) → an equal debit that restores the balance, all net-zero on your test account. This catches a backend that returns 'success' with an unchanged balance (the #1 activation rejection). Rate-limited to 6 calls per minute (429 → wait a minute). Requires callback_base_url, test_uid and test_token on the project.

Retourne: { ok: boolean, checks: Array<{ name, url, ok, http_status, error, response }>, error_codes_contract: string } — One entry per check: the three callbacks, the two negative checks (forged-signature-rejected, wrong-token-rejected), and the three balance-movement checks (balance-credit-applied, balance-idempotent, balance-debit-restored). error_codes_contract restates the rule: intentional blocking must return errorCode 30001; 4005 is reserved for real failures (provider monitoring alerts on it).