Licensee Implementation

Service-to-Service Authentication

All requests sent from the Game Provider to the Licensee are executed through direct backend-to-backend communication. Therefore, the Licensee must provide an authentication mechanism capable of verifying the request source, ensuring that requests originate from an authorized Game Provider system.

In a production environment, wallet operations (such as debits, credits, or transaction cancellations) directly affect player funds. Without proper source verification, any third party with access to the API could forge transaction requests, such as submitting fake credit or debit operations, resulting in financial risk.

In practice, such APIs typically use HTTP Headers to carry client identification and signature information, and rely on shared secrets or public/private key mechanisms for verification. Many online gaming wallet integration APIs follow the same approach: the Licensee provides the API endpoint, while the Game Provider includes signature data in each request for validation.

After completing S2S authentication, the Licensee must implement the following APIs to support the transaction workflow.

Game Service Context

When a Licensee allows a Player to launch a game using the game launch flow, the Game Service will construct the following information:

{
  "id": "Player-uniqueID",
  "currency": "USD",
  "playMode": "credit",
  "session": "<OPTIONAL>",
  "language": "<OPTIONAL>",
  "nickname": "<OPTIONAL>",
  "launch": {
    "mode": "direct",
    "licensee": "asia-platform-1",
    "agents": [
      // ... Agent Layer
    ],
    "gameId": "baccarat001",
    "units": [
      // ... Game Units
    ],
    "params": {
      "category": "vip",
      "campaign": "summer2026",
      // ...More Params
    }
  }
}

Licensee can refer to the above content to negotiate with the Game Provider which payloads should be sent for the HTTP Request.

API Define

Request

The Game Provider will include the following information in the Body:

Split Debit and Credit RequestMerge Debit and Credit Request

{
  "entity": "playerid-q83vEjRWeJCrze8SNFZ4kA==",
  "gameId": "GAME_1684",
  "roundId": <uint64>,
  "currency": "<Currency Code>",
  "amount": 1000.00
}

{
  "entity": "playerid-q83vEjRWeJCrze8SNFZ4kA==",
  "gameId": "GAME_1684",
  "roundId": <uint64>,
  "currency": "<Currency Code>",
  "debit": 1000.00,
  "credit": 50
}

Field	Description
`entity`	Identifies the wallet owner for this request. Depending on Licensee requirements, this is typically either `player.id` or `player.session`. See Game Launch Flow for details.
`gameId`	Unique identifier of the game
`roundId`	The smallest unit representing a game round
`currency`	Currency code
`amount`, `bet`, `credit`	Transaction amount, supporting precision up to four decimal places

Additional Information

The fields above represent the minimum payload that the Game Provider will include. If the Licensee has no specific requirements, only this payload will be sent.
If the Licensee requires additional data, the Game Provider will include it within the context field.

{
  "entity": "playerid-q83vEjRWeJCrze8SNFZ4kA==",
  "gameId": "GAME_1684",
  "roundId": <uint64>,
  "currency": "<Currency Code>",
  "amount": 1000.00,
  "context": {
    "aud": <Licensee Identifier>,
    /* 其他要求欄位 */
  }
}

context.aud will contain the Licensee identifier for verification purposes; any additional data will be placed under context.*.

If additional fields are required to be handled by the Game Provider, please contact your KAM.

Response

The Game Provider does not impose strict requirements on the Response, but there are minimum expectations:

If the Licensee cannot guarantee that the Player’s balance remains unchanged during gameplay, the response must include balance.

{
  "balance": 1000.00
}

Error Response Format

Below defines the error response format that the Licensee should return when a request fails, along with reference error codes:

If the Licensee already has custom error codes, they should be provided to the Game Provider for handling.
If the Licensee uses the following error codes but requires additional ones, they should also be shared with the Game Provider.
error.reason may be an empty string.

{
  "code": "<ERROR_CODE>",
  "reason": "<ERROR_REASON>"
}

Error Code	Type	Description	Game Provider Handling
`OK`	`Success`	No error	Process transaction successfully
`DEBIT_EXISTS`	`Complete`	The debit transaction already exists	Treat as completed; do not deduct again
`CREDIT_EXISTS`	`Complete`	The credit transaction already exists	Treat as completed; do not credit again
`DEBIT_INSUFFICIENT_FUNDS`	`Complete`	Insufficient balance for the bet	Bet fails; display insufficient balance message
`ERR_INVAILD_PARAMETER`	`Complete`	Invalid request parameters	Request fails; display error message
`FATAL_UNAVAILABLE`	`Fatal`	System temporarily unavailable	Bet fails; show system error message
`FATAL_SESSION_INVALID`	`Fatal`	Player session is invalid	Request fails; prompt re-login
`FATAL_SESSION_LOCKED`	`Fatal`	Player account is locked	Request fails; prompt user to contact support

Success: The request is processed successfully with the expected outcome (e.g., a bet is placed and accepted).
Complete: The request is processed but results in a non-critical outcome (e.g., bet rejected due to insufficient balance).
Fatal: A critical error; the Game Provider should immediately terminate the player’s session or reject further requests.
The Game Provider will prioritize forcing the Player to exit the game.

`POST /api/check`

REQUIRED

Balance Reservation

The Licensee may reserve player balance before the game starts via the Deposit API or authentication attributes, and have it > returned by the Game Provider when the game ends.

This model is recommended for long-session games where balances should not change arbitrarily during gameplay, such as Texas Hold’em, > Baccarat, and Blackjack.

In such cases, it is recommended to use player.session and implement /api/close to explicitly define the reservation duration and > settlement behavior.

When a player enters the game, reconnects, or before placing a bet, the Game Provider will call this API.

The Licensee must:

Verify that the player exists in the system; otherwise return an error to terminate the session.
Check whether the player is allowed to perform transactions (e.g., fraud control, account lock, region restriction).
Return the current balance and currency.

This API does not modify funds.

`POST /api/debit`

REQUIRED

When a player places a bet in the game, the Game Provider will send a request to the Licensee wallet system.

When handling this request, the Licensee should:

The Game Provider should include a unique value (e.g., uuid or nonce) in the request to detect duplicate bets.
- It is recommended to configure this based on the desired deduplication window, using a cache mechanism with configurable TTL.
- If a game round lasts 30 seconds, the nonce can be set with a TTL of 30 seconds, allowing reuse in the next round.
- If uniqueness is required within a full day, the nonce TTL can be set to 1 day.
Verify that the player has sufficient balance. If the balance is insufficient, the Licensee should reject the transaction and return an error response.
If the balance is sufficient, the Licensee should deduct the specified amount from the player’s account and record the transaction as a valid bet.
After completing the deduction, the Licensee should return the updated player balance and the transaction result. The Game Provider will determine whether the bet was successful based on this response.

`POST /api/credit`

REQUIRED

Must Respond

For Game Provider handling, once a Player’s bet request has been successfully processed, the Game Provider will proceed with settlement based on the last deducted amount, regardless of whether the Licensee responds to the credit request—even in cases of failure or timeout.

bet must ensure the Player’s balance does not increase
credit must ensure the Player’s balance does not decrease

The Game Provider uses this as the fundamental logic for game flow processing.

After a game round ends, the Game Provider calculates the payout based on the game result and sends a credit request.

When handling this request, the Licensee should:

Prevent duplicate credits if the same request is resent due to network issues (refer to duplicate handling in debit).
In Mixed Settlement mode, each debit typically corresponds to a credit or cancel.
In Gamewise Settlement mode, a player may issue multiple debit requests within a single round, followed by one aggregated credit.

Regardless of the settlement mode, the Licensee must ensure that the player’s balance is correctly increased and return the updated balance information.

`POST /api/cancel`

OPTIONAL

This API is used to cancel a previously successful debit transaction and refund the deducted amount back to the player’s account.

Cancellation typically occurs under the following conditions:

The game round fails to complete properly, such as due to a service failure or network interruption.
The bet is determined to be invalid based on game logic.
The game system detects an abnormal state after the bet and requires a rollback.

When the Licensee receives a cancel request, it should locate the corresponding debit transaction and verify that it exists and has not yet been settled. If the debit has already been canceled or settled, the Licensee must avoid issuing duplicate refunds and return an appropriate response.

Whether cancel is required depends on the transaction flow and failure model. If the system can fully prevent duplicate requests before the bet is processed, this API should be avoided whenever possible.

Perform duplicate validation in both debit and credit

Use when a round is determined invalid (less common in electronic games)

Clearly define whether a bet should still be settled if the player disconnects after betting but before settlement

`POST /api/promo_payout`

OPTIONAL

This API is used to issue promotional rewards or campaign bonuses.

Unlike credit, promo_payout is not tied to any gameplay betting activity. Instead, it represents rewards generated by the Game Provider or operational campaigns.

Typical scenarios include:

Player completes a campaign task
Leaderboard rewards
Tournament or competition prizes
Promotional free credits

When the Licensee receives this request, it should add the specified amount to the player’s wallet and record the transaction as a promotional credit. Since promotional rewards are often subject to campaign analytics and financial tracking, the Licensee system should clearly distinguish these transactions from standard game payouts.

`POST /api/close`

OPTIONAL

This API is used to notify the Licensee that a game round has been completed.

In certain game types, players may place multiple bets within the same round, such as in roulette or baccarat. In these cases, the system typically uses the Gamewise Settlement model, where all transactions are settled collectively at the end of the round.

The primary purpose of the close API is to inform the Licensee system that the game round has finished, and it can be used for the following:

Confirm that all transactions related to the round have been fully processed
Update round status or settlement statistics
Release system resources associated with the round

This API itself does not usually involve any fund movement, but it plays an important role in operational state synchronization.