Skip to main content

Operator API Implementation Guide

In Seamless Wallet Mode, Operators need to implement a unified API for VP to call, to achieve Balance queries, Bet Settlements, and transaction processing.

Architecture Overview​

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

API Implementation Description​

Operators need to provide a set of callback URLs on their own servers. Operators should determine the operation to perform based on the action parameter in the request:

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

Unified URL​

Operators only need to provide a 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 between different operations.

Unified Request Header Content​

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

Implementation Requirements​

1. Security Requirements​

  • ✅ Encrypted Transmission: All request content uses AES-256-GCM encryption, responses use plaintext JSON format.
  • ✅ HTTPS: HTTPS must be used in 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 uniformly plaintext JSON, with the following fixed format:

{
  "status": "0000",
  "errText": "",
  "balance": 12345.67,
  "responseTime": "2024-12-11T01:23:38.271Z"
}
FieldTypeDescription
statusstringStatus Code, see 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 for both, and Operators need to handle them separately during implementation. The 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 Games (FISH)​

Transaction Frequency​

  • When idle: balance Query Balance is called once every 3 seconds
  • When firing bullets: betNSettle Settlement is called once every 5 seconds

Transaction Features​

  • Fish Game Special Transaction (Jackpot and Card): betSourceId = 13, includes Normal Bet triggered jackpotWin, backpack triggered jackpotWin, and other backpack triggered Items (e.g., cannon cards).
  • jackpotWin transactions sent independently: Transactions for Normal Bet triggered jackpotWin will be sent separately. For example, if one of four Normal Bets hits a jackpot, the remaining 3 bets are combined into one, and the jackpot-hitting bet is sent as a separate transaction.
  • Item Retry Mode: Fish Game Special Transaction also applies the Item retry process. If betNSettle fails, it will not trigger rollback. Instead, retryBet will be used to continuously retry until the Operator responds with a transaction Success.

API Restrictions​

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

Important Notes​

  • Fish game transactions have latency. When a Player is in a Fish Game, please add a transaction lock to prevent malicious withdrawals.
  • For Balance checks, please use netWin (winAmt - actualBetAmt).

Slot Games (SLOT)​

Transaction Frequency​

  • When idle: balance Query Balance is called once every 10 seconds

Important Notes​

  • For Balance checks, please use actualBetAmt.

FAQ​

Q1: How to distinguish 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 after the Player closes the Game or logs out.

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

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

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

A: 3 seconds.

Q5: Which transactions enter the Bet retry process?​

A: Item and Operator Card transactions will not trigger Bet cancellation, but will continuously retry through the "Bet retry" API.

Q6: Can the callback URL be adjusted?​

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

Q7: When 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, it can respond with 1006. Under this Status, the transaction is deemed a failure and will not trigger a retry.

Technical Support​

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

Next Steps​