Skip to main content

Operator API Implementation Guide

In Seamless Wallet Mode, the Operator needs to implement a unified API for VP to call, to achieve Balance inquiry, Bet Settlement, and transaction processing.

Architecture Overview​

In Seamless Wallet Mode, the Player's Balance is Managed by Operator. VP, as the Game service provider, needs to Query Balance from the Operator and process transactions.

API Implementation Description​

The Operator needs to provide a set of callback URLs on their server. The Operator needs to determine the operation to perform based on the action parameter in the request:

ActionDescriptionPriority
balanceQuery player available balance in real-timeMandatory
betNSettleHandle Game Bet and SettlementMandatory
rollbackRollback abnormal transactionsMandatory
retryBetBet retry mechanismMandatory

Unified URL​

The Operator only needs to provide one set of callback URLs, for example:

POST https://operator.example.com/api/wallet

VP will include the action Field in the decrypted request parameters to distinguish different operations.

Unified Request Header Content​

FieldTypeDescription
x-agentidstringAgent to which this transaction belongs
x-custom-system-trace-idstringTransaction tracking code, UUID format

Implementation Requirements​

1. Security Requirements​

  • ✅ Encrypted Transmission: All request content is encrypted using AES-256-GCM, responses use plaintext JSON format.
  • ✅ HTTPS: HTTPS must be used in the production environment.
Encryption Description

Algorithm: AES-256-GCM

  • Key length: 256 bits (32 bytes)
  • IV length: 96 bits (12 bytes)
  • Authentication tag length: 128 bits (16 bytes)

cipherText format:

ivBase64(16 characters) + authTagBase64(24 characters) + encryptedDataBase64

2. Response Format Requirements​

Response Format Description

All Operator API response formats are unified as plaintext JSON, with the following fixed format:

{
  "status": "0000",
  "errText": "",
  "balance": 12345.67,
  "responseTime": "2024-12-11T01:23:38.271Z"
}
FieldTypeDescription
statusstringStatus Code, refer to each API Description for details
errTextstringError message, empty string on Success
balancenumberPlayer Balance after operation
responseTimestringResponse time

3. Performance Requirements​

  • ⚡ Response Time: Average response time should be < 3000ms; exceeding this is considered a timeout.

Game Kind Differences​

VP supports two Game Kinds: SLOT and FISH. The transaction frequency and transaction Features differ between the two, and the Operator must handle them separately during implementation. Game Kind can be determined by the gameKind Field returned by Query Game List. For code mapping, please refer to Appendix - Game Kind Mapping Table.

FISH​

Transaction Frequency​

  • When idle: Call balance to Query Balance once every 3 seconds
  • When firing bullets: Call betNSettle for Settlement once every 5 seconds

Transaction Features​

  • Fish Game Special Transaction (Jackpot and Card): betSourceId = 13, includes Normal Bet triggering jackpotWin, backpack triggering jackpotWin, and other Items triggered by backpack (e.g., cannon cards).
  • jackpotWin transactions sent independently: Transactions where Normal Bet triggers jackpotWin will be sent separately. For example, if one out of four Normal Bets hits a jackpot, the other 3 bets are merged into one, and the jackpot-winning bet is sent as a separate transaction.
  • Item retry mode: Fish Game Special Transactions also apply the Item retry process; if betNSettle fails, it will not trigger rollback but instead use retryBet to continuously retry until the Operator responds with transaction Success.

API Restrictions​

  • Does not support Query Bet Replay
  • Currently no Operator Card related functions

Important Notes​

  • Fish Game transactions have a delay; please apply a transaction lock when a Player is in a Fish Game to prevent malicious withdrawals.
  • For Balance checks, please use netWin (winAmt - actualBetAmt).

SLOT​

Transaction Frequency​

  • When idle: Call balance to Query Balance once every 10 seconds

Important Notes​

  • For Balance checks, please use actualBetAmt.

FAQ​

Q1: How to distinguish between different operations?​

A: VP will include the action Field (balance, betNSettle, rollback, retryBet) in the decrypted request parameters. The Operator routes to the corresponding processing logic based on this Field.

Q2: How long should the Token validity period be set?​

A: 24 hours is recommended. The Token should be invalidated when the Player closes the Game or logs out.

Q3: How many decimal places should the Balance precision be set to?​

A: Supports up to 4 decimal places (0.0001), but must support at least 2 decimal places (0.01).

Q4: How long until a transaction is considered timed out?​

A: 3 seconds

Q5: Which transactions enter the Bet retry process?​

A: Items and Operator Cards transactions will not trigger Bet cancellation, but will continuously retry via the "Bet retry" API.

Q6: Can the callback URL be adjusted?​

A: Yes, we do not specify any format for the callback URL returned in transactions. It can be configured and verified through the backend.

Q7: Under what circumstances is errorCode 1006 (invalid session) triggered?​

A: When the Operator believes the Player is no longer online, but still receives transaction requests from that Player, they can respond with 1006. In this Status, the transaction is deemed failed and will not trigger a retry.

Technical Support​

If you encounter any problems during implementation, please Contact Customer Support Team and include the UUID from the Headers for easier issue tracking.

Next Steps​