Platform API平台接口
Launch a game进游戏
A one-time launch URL for a player. The first launch of an extPlayerId creates the player on our side.给玩家签一次性进游戏地址；某个 extPlayerId 第一次进游戏时平台自动建玩家。
POST
/merchant/v1/games/launchCreates a one-time launch URL for a player. On the first launch of an extPlayerId the player is created on our side and bound to the currency returned by your /auth.
给玩家生成一次性的进游戏地址。某个 extPlayerId 第一次进游戏时，平台自动建玩家，并绑定商户 /auth 返回的币种。
Request请求
platformstringrequired必填
evo. pp is reserved and not open yet: it returns GAME_UNAVAILABLE.evo。pp 已预留但尚未开放，传它返回 GAME_UNAVAILABLE。tableCodestringone of二选一
Enter this table directly.直接进这张桌。
lobbyCodestringone of二选一
Enter the lobby (main page or a category). Send exactly one of
tableCode / lobbyCode.进大厅（首页或某个分类）。tableCode 与 lobbyCode 必须且只能给一个。tokenstringrequired必填
Short-lived player token issued by you, ≤ 256 bytes. We pass it to your
/auth.商户签发的短期玩家 token，≤ 256 字节。平台原样传给商户 /auth。extPlayerIdstringrequired必填
Your player id,
^[A-Za-z0-9_-]{1,64}$. Must equal the extPlayerId your /auth returns for the token.商户侧玩家编号，^[A-Za-z0-9_-]{1,64}$。必须与 /auth 对这个 token 返回的 extPlayerId 相同。nicknamestringoptional可选
≤ 32 characters. Applied only if the player has no nickname yet. Unique within your merchant account: if it is already taken it is ignored (no error) and the player picks a nickname inside the game. Control characters, bidirectional controls and zero-width characters (
U+200B–U+200D, U+2060, U+FEFF) → INVALID_PARAM.≤ 32 个字符，只在玩家还没有昵称时生效。同一商户内唯一：已被占用时忽略（不报错），玩家进游戏后自己设置。含控制字符、双向控制符、零宽字符（U+200B–U+200D、U+2060、U+FEFF）→ INVALID_PARAM。langstringoptional可选
Language code, e.g.
en, en-US, pt-BR, zh-Hans. Applied only if the player has no language yet. Unknown values are ignored, not stored, and never fail the request.语言代码，如 en、en-US、pt-BR、zh-Hans。只在玩家还没有语言时生效。不认识的值忽略、不保存，也不会让请求失败。countrystringoptional可选
ISO 3166-1 alpha-2
ipstringoptional可选
Player IP as seen by you. If omitted we use the IP that opens the launch URL.商户看到的玩家 IP；不传则用玩家打开进游戏地址时的 IP。
devicestringoptional可选
desktop or mobile; omitted = detected by the client.desktop 或 mobile；不传由客户端自己判断。homeUrlstringoptional可选
Absolute
http(s) URL for "back to site" in this session, ≤ 1024 bytes, no user name or password. Default: your configured value.本次会话「返回商户」的绝对 http(s) 地址，≤ 1024 字节，不能带用户名或密码；不传用商户配置值。cashierUrlstringoptional可选
Absolute
http(s) URL for "deposit" in this session; same rules as homeUrl. Default: your configured value.本次会话「充值」的绝对 http(s) 地址，规则同 homeUrl；不传用商户配置值。Processing order处理顺序
common checks (Overview)
→ field validation (format, exactly one target, absolute URLs, nickname) → INVALID_PARAM
→ platform not open yet (pp) → GAME_UNAVAILABLE
→ target exists on this platform → GAME_NOT_FOUND
→ target open for your account and not under maintenance → GAME_UNAVAILABLE
→ our player (if exists) frozen / disabled → PLAYER_DISABLED
→ call your POST /auth {token, platform}
timeout / transport error / INTERNAL_ERROR / MAINTENANCE → WALLET_UNAVAILABLE
INVALID_TOKEN → INVALID_TOKEN
PLAYER_DISABLED → PLAYER_DISABLED
any other code, or response failing Strict response validation → WALLET_ERROR
extPlayerId ≠ request extPlayerId → PLAYER_MISMATCH
currency not enabled on our platform → CURRENCY_NOT_SUPPORTED
player already bound to another currency → CURRENCY_MISMATCH
→ direct table entry without configuration for this currency → GAME_UNAVAILABLE
→ create the player on first launch; store balance snapshot
→ OK {launchUrl, …}
We check what we can before calling your wallet, so a malformed request never reaches /auth.
先查平台能查的、最后才调商户钱包：参数错误的请求不会打到商户 /auth。
Response data响应 data
launchUrlstring
One-time URL. Redirect the player immediately.一次性地址，立即把玩家重定向过去。
expiresAtstring
Expiry of the URL (5 minutes after issue).地址失效时间（签发后 5 分钟）。
playerUidstring
Our public id of the player (10 lowercase letters/digits).平台玩家对外编号（10 位小写字母数字）。
currencystring
The player's bound currency.玩家绑定的币种。
langstring
Language used for this session.本次会话实际使用的语言。
Multiple tables多张桌One player has one game session per platform, and that session can play several tables at once inside the same game window (multi-window and the multi-table view are built into the game client). You do not need one launch per table. Calling
games/launch again for the same player and platform starts a new session and disconnects the previous game window; do it when the player re-enters, not to open a second table.一个玩家在一个平台上只有一个游戏会话，这个会话可以在同一个游戏窗口里同时玩多张桌（多窗口与多桌视图由游戏客户端提供），不需要每张桌各调一次进游戏。同一玩家同一平台再次调用 games/launch 会开新会话，之前的游戏窗口随即断开；只在玩家重新进入时调用，不要用它来开第二张桌。Result codes结果码
OKINVALID_PARAMMERCHANT_DISABLEDGAME_NOT_FOUNDGAME_UNAVAILABLEPLAYER_DISABLEDINVALID_TOKENPLAYER_MISMATCHCURRENCY_NOT_SUPPORTEDCURRENCY_MISMATCHWALLET_UNAVAILABLEWALLET_ERROR
In addition to the common codes listed in另可能返回通用结果码，见 Result codes结果码.
Test cases测试用例
Run each case against the staging environment before go-live. Signature, timestamp, request ID and IP cases apply to every endpoint and are listed under上线前请在测试环境逐条执行。签名、时间戳、请求编号与 IP 相关用例适用于所有接口，见 Authentication签名认证.
G-01 Normal正常 Direct table entry直接进桌 Expected期望 OKtableCode + valid tokentableCode + 有效 token
Opening launchUrl lands on the table; currency = your /auth currency.打开 launchUrl 直接进桌；currency 等于 /auth 回的币种。
G-02 Normal正常 Lobby entry进入大厅 Expected期望 OKlobbyCode evo_lobby + valid tokenlobbyCode evo_lobby + 有效 token
Lands on the lobby.进到大厅首页。
G-03 Rejection拒绝 Both targets given同时给出两个目标 Expected期望 INVALID_PARAMtableCode and lobbyCode together同时给出 tableCode 与 lobbyCode
Your /auth is not called.不会调商户 /auth。
G-04 Rejection拒绝 Unknown table机台不存在 Expected期望 GAME_NOT_FOUNDtableCode evo_unknown_01tableCode evo_unknown_01
Refresh the catalog.刷新目录。
G-05 Rejection拒绝 Platform not open平台未开放 Expected期望 GAME_UNAVAILABLEplatform pp, lobbyCode pp_lobbyplatform pp，lobbyCode pp_lobby
G-06 Rejection拒绝 Token rejected by the merchant /auth商户 /auth 不认 token Expected期望 INVALID_TOKENA token the merchant does not recognize商户不认识的 token
No player created.不建玩家。
G-07 Rejection拒绝 Player mismatch玩家不一致 Expected期望 PLAYER_MISMATCHextPlayerId differs from the one /auth returnsextPlayerId 与 /auth 返回的不同
G-08 Rejection拒绝 Currency not supported币种未开通 Expected期望 CURRENCY_NOT_SUPPORTED/auth returns currency ZZZ/auth 返回币种 ZZZ
G-09 Rejection拒绝 Currency changed币种变更 Expected期望 OK → CURRENCY_MISMATCHSame extPlayerId; the player is bound to EUR, /auth returns USD同一 extPlayerId；我方玩家绑定 EUR，/auth 返回 USD
Use one extPlayerId per currency.每个币种用一个 extPlayerId。
G-10 Rejection拒绝 Merchant wallet unavailable商户钱包不可用 Expected期望 WALLET_UNAVAILABLE/auth answers MAINTENANCE (the Demo site is disabled)/auth 回 MAINTENANCE（停用 Demo 站点构造）
Retry later.稍后再试。
G-11 Rejection拒绝 Invisible characters in nickname昵称含零宽字符 Expected期望 INVALID_PARAMnickname "Lucky\u200B7"nickname "Lucky\u200B7"
message: invalid field: nickname.message：invalid field: nickname。
G-12 Rejection拒绝 Unsafe homeUrlhomeUrl 不安全 Expected期望 INVALID_PARAMhomeUrl "javascript:alert(1)"homeUrl "javascript:alert(1)"
message: invalid field: homeUrl.message：invalid field: homeUrl。
G-13 Normal正常 Launch URL is single-use进入游戏地址一次性有效 Expected期望 HTTP 302 → HTTP ≠ 302Open the launchUrl from G-01 twice打开 G-01 返回的 launchUrl 两次
The second open shows a "link expired" page.第二次打开显示「链接已失效」。
G-14 Rejection拒绝 Neither target given未给出目标 Expected期望 INVALID_PARAMNeither tableCode nor lobbyCode既无 tableCode 也无 lobbyCode
G-15 Rejection拒绝 Unknown lobby大厅不存在 Expected期望 GAME_NOT_FOUNDlobbyCode evo_lobby_nothinglobbyCode evo_lobby_nothing
G-16 Boundary边界 Token of 256 bytestoken 长 256 字节 Expected期望 INVALID_TOKENMaximum length (unknown to the merchant)长度上限（商户不认识）
G-17 Boundary边界 Token of 257 bytestoken 长 257 字节 Expected期望 INVALID_PARAMOne byte over the limit超出上限 1 字节
G-18 Boundary边界 extPlayerId of 64 charactersextPlayerId 长 64 个字符 Expected期望 PLAYER_MISMATCHMaximum length (not the token's player)长度上限（不是 token 对应的玩家）
G-19 Boundary边界 extPlayerId of 65 charactersextPlayerId 长 65 个字符 Expected期望 INVALID_PARAMOne character over the limit超出上限 1 个字符
G-20 Rejection拒绝 Invalid characters in extPlayerIdextPlayerId 含不允许的字符 Expected期望 INVALID_PARAM ×2"pt.main", "玩家01""pt.main"、"玩家01"
G-21 Boundary边界 Nickname of 32 characters昵称长 32 个字符 Expected期望 OK32 characters including CJK and emoji32 个字符，含中文与 emoji
G-22 Boundary边界 Nickname of 33 characters昵称长 33 个字符 Expected期望 INVALID_PARAMOne character over the limit超出上限 1 个字符
G-23 Rejection拒绝 Control characters in nickname昵称含控制字符 Expected期望 INVALID_PARAM ×2A line feed; a right-to-left override (U+202E)换行符；从右向左覆盖符（U+202E）
G-24 Boundary边界 Country code国家代码 Expected期望 OK, INVALID_PARAM"us" (normalized), "USA""us"（规范化为大写）、"USA"
G-25 Boundary边界 Player IP玩家 IP Expected期望 OK, INVALID_PARAM ×2"2001:db8::1", "fe80::1%eth0", "999.0.0.1""2001:db8::1"、"fe80::1%eth0"、"999.0.0.1"
G-26 Boundary边界 Device设备类型 Expected期望 OK, INVALID_PARAM"mobile", "tablet""mobile"、"tablet"
G-27 Boundary边界 homeUrl lengthhomeUrl 长度 Expected期望 OK, INVALID_PARAM1,024 and 1,025 bytes1,024 字节与 1,025 字节
G-28 Rejection拒绝 Unsafe cashierUrlcashierUrl 不安全 Expected期望 INVALID_PARAM ×2"ftp://merchant.example.com", "https://u:p@merchant.example.com""ftp://merchant.example.com"、"https://u:p@merchant.example.com"
G-29 Boundary边界 Unknown language falls back不认识的语言回退 Expected期望 OKlang "xx-YY"lang "xx-YY"
G-30 Boundary边界 Surrounding spaces are trimmed首尾空格被去除 Expected期望 OKplatform, tableCode and extPlayerId padded with spacesplatform、tableCode、extPlayerId 首尾带空格
G-31 Rejection拒绝 Player disabled by the merchant玩家被商户停用 Expected期望 PLAYER_DISABLED/auth answers PLAYER_DISABLED/auth 回 PLAYER_DISABLED
G-32 Rejection拒绝 Wrong field type字段类型错误 Expected期望 INVALID_PARAMtoken sent as a numbertoken 以数字发送