Wallet API钱包回调接口

Authenticate认证玩家

Called once during games/launch: exchange the launch token for the player.games/launch 时调一次：用进游戏 token 换玩家信息。

POST{callbackUrl}/auth

Implemented by the merchant · called by the platform商户实现 · 平台调用 · timeout超时 5 s

Called during games/launch. Validate the token and return the player.

在 games/launch 时调用。校验 token，返回玩家信息。

tokenstring

The token from games/launch.games/launch 里的 token。

platformstring

Platform being launched.要进的平台。

extPlayerIdstringrequired必填

The player bound to the token.token 对应的玩家。

currencystringrequired必填

The player's currency — becomes the bound currency on first launch.玩家币种，第一次进游戏时成为绑定币种。

balancestringrequired必填

Current balance.当前余额。

nicknamestringoptional可选

Used if the launch request had none.进游戏请求没带昵称时使用。

langstringoptional可选

Used if the launch request had none.进游戏请求没带语言时使用。

Token policy is yours (lifetime, single use). We call /auth once per launch. For the conformance test you provide one long-lived test token (API conformance test).

token 的有效期、是否一次性由商户决定。每次进游戏时平台调用一次 /auth。对接测试需要商户提供一个长期有效的测试 token（接口对接测试）。

Result codes结果码

OK INVALID_TOKEN PLAYER_DISABLED

In addition to the common codes listed in另可能返回通用结果码，见 Result codes结果码.

Test cases测试用例

The conformance test sends the following 3 requests to /auth. Each response must match the expected result exactly.接口对接测试会向 /auth 发送以下 3 个请求，每个响应都必须与期望结果完全一致。 All test cases全部测试用例

AUTH-01 blocking阻断级 Authentication with a valid token有效 token 认证 Expected期望 OK

/auth {token: TK}

extPlayerId matches ^[A-Za-z0-9_-]{1,64}$; currency is enabled on the platform; balance is a valid amount. P and C are recorded. A failure aborts the test.extPlayerId 符合 ^[A-Za-z0-9_-]{1,64}$；currency 为平台已开通币种；balance 为合法金额。记录 P 与 C。失败则测试中止。

AUTH-02 blocking阻断级 Authentication with an invalid token无效 token 认证 Expected期望 INVALID_TOKEN

/auth {token: <random>}

No player data is returned.不返回玩家数据。

AUTH-03 warning警告级 Repeated authentication with the same token同一 token 重复认证 Expected期望 OK

/auth {token: TK}

extPlayerId and currency are identical to AUTH-01.extPlayerId 与 currency 与 AUTH-01 一致。

from flask import Flask, request, Response from merchant_sign import verify, envelope, OK app = Flask(__name__) @app.post("/wallet/auth") def auth(): raw = request.get_data() # verify the raw bytes BEFORE parsing JSON check = verify(SECRET_KEY, MERCHANT_CODE, request.headers, "POST", request.path, raw) if check != OK: return Response(envelope(check), mimetype="application/json") data = request.get_json() # Look up the token. Unknown, expired or used: answer INVALID_TOKEN. # Player blocked on your side: answer PLAYER_DISABLED. # Otherwise answer the player, its currency and current balance (amounts are strings). return Response(envelope("OK", "OK", {"extPlayerId":"u123_USD","currency":"USD","balance":"1250.50","nickname":"Lucky7","lang":"en"}), mimetype="application/json")

http.HandleFunc("POST /wallet/auth", func(w http.ResponseWriter, r *http.Request) { raw, _ := io.ReadAll(http.MaxBytesReader(w, r.Body, 1<<20)) // verify the raw bytes BEFORE decoding w.Header().Set("Content-Type", "application/json") if check := merchantsign.Verify(secretKey, merchantCode, r.Header, r.Method, r.URL.EscapedPath(), raw, time.Now()); check != merchantsign.OK { w.Write(merchantsign.Envelope(check, "", nil)) return } var in map[string]any _ = json.Unmarshal(raw, &in) // Look up the token. Unknown, expired or used: answer INVALID_TOKEN. // Player blocked on your side: answer PLAYER_DISABLED. // Otherwise answer the player, its currency and current balance (amounts are strings). w.Write(merchantsign.Envelope("OK", "OK", json.RawMessage(`{"extPlayerId":"u123_USD","currency":"USD","balance":"1250.50","nickname":"Lucky7","lang":"en"}`))) // always HTTP 200 })

@RestController class WalletController { @PostMapping(value = "/wallet/auth", produces = "application/json") String auth(@RequestBody byte[] raw, @RequestHeader Map<String, String> headers) throws IOException { String check = MerchantSign.verify(SECRET_KEY, MERCHANT_CODE, headers, "POST", "/wallet/auth", raw, System.currentTimeMillis()); if (!check.equals(MerchantSign.OK)) { return "{\"code\":\"" + check + "\",\"message\":\"" + check + "\"}"; } JsonNode in = new ObjectMapper().readTree(raw); // parse only after the signature checks out // Look up the token. Unknown, expired or used: answer INVALID_TOKEN. // Player blocked on your side: answer PLAYER_DISABLED. // Otherwise answer the player, its currency and current balance (amounts are strings). return "{\"code\":\"OK\",\"message\":\"OK\",\"data\":" + "{\"extPlayerId\":\"u123_USD\",\"currency\":\"USD\",\"balance\":\"1250.50\",\"nickname\":\"Lucky7\",\"lang\":\"en\"}" + "}"; } }

<?php require 'MerchantSign.php'; // /wallet/auth header('Content-Type: application/json'); $raw = file_get_contents('php://input'); // verify the raw bytes BEFORE json_decode $check = MerchantSign::verify(SECRET_KEY, MERCHANT_CODE, getallheaders(), $_SERVER['REQUEST_METHOD'], parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH), $raw); if ($check !== MerchantSign::OK) { echo MerchantSign::envelope($check); exit; } $in = json_decode($raw, true); // Look up the token. Unknown, expired or used: answer INVALID_TOKEN. // Player blocked on your side: answer PLAYER_DISABLED. // Otherwise answer the player, its currency and current balance (amounts are strings). echo MerchantSign::envelope('OK', 'OK', json_decode('{"extPlayerId":"u123_USD","currency":"USD","balance":"1250.50","nickname":"Lucky7","lang":"en"}', true));

app.MapPost("/wallet/auth", async (HttpRequest req) => { using var ms = new MemoryStream(); await req.Body.CopyToAsync(ms); var raw = ms.ToArray(); // verify the raw bytes BEFORE deserializing var headers = req.Headers.ToDictionary(h => h.Key, h => h.Value.ToString()); var check = MerchantSign.Verify(SecretKey, MerchantCode, headers, req.Method, req.Path, raw); if (check != MerchantSign.Ok) return Results.Json(new { code = check, message = check }); var input = JsonDocument.Parse(raw).RootElement; // Look up the token. Unknown, expired or used: answer INVALID_TOKEN. // Player blocked on your side: answer PLAYER_DISABLED. // Otherwise answer the player, its currency and current balance (amounts are strings). return Results.Text("{\"code\":\"OK\",\"message\":\"OK\",\"data\":" + "{\"extPlayerId\":\"u123_USD\",\"currency\":\"USD\",\"balance\":\"1250.50\",\"nickname\":\"Lucky7\",\"lang\":\"en\"}" + "}", "application/json"); });

require 'sinatra' require 'json' require_relative 'merchant_sign' post '/wallet/auth' do content_type :json raw = request.body.read # verify the raw bytes BEFORE JSON.parse check = MerchantSign.verify(SECRET_KEY, MERCHANT_CODE, request.env, 'POST', request.path_info, raw) return MerchantSign.envelope(check) unless check == MerchantSign::OK input = JSON.parse(raw) # Look up the token. Unknown, expired or used: answer INVALID_TOKEN. # Player blocked on your side: answer PLAYER_DISABLED. # Otherwise answer the player, its currency and current balance (amounts are strings). MerchantSign.envelope('OK', 'OK', JSON.parse('{"extPlayerId":"u123_USD","currency":"USD","balance":"1250.50","nickname":"Lucky7","lang":"en"}')) end