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 inquiry, Bet Settlement, and transaction processing.

Architecture Overview​

In Seamless Wallet Mode, the Player's Balance is Managed by Operator. VP, as the Games 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 servers. Operators must determine the operation to be performed based on the action parameter in the request:

ActionDescriptionPriority
balanceQuery player available balance in real-timeRequired
betNSettleProcess Games Bet and SettlementRequired
rollbackRollback abnormal transactionsRequired
retryBetBet retry mechanismRequired

Unified URL​

Operators only need to provide a single callBack URL, for example:

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

VP will include the action Field in the decrypted parameters of the request to distinguish between 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, and responses use plaintext JSON format.
  • ✅ HTTPS: HTTPS must be used in production environments.
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, 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​

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.

Slot Machines (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 different operations?​

A: VP will include the action Field (balance, betNSettle, rollback, retryBet) in the decrypted parameters of the request. 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 Games or logs out.

Q3: How many decimal places should the 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: Transactions for Items and Operator Cards do not Trigger Bet cancellation; they will be continuously retried 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 by transactions. It can be set and verified through the backend.

Q7: In what scenarios is errorCode 1006 (invalid session) Triggered?​

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

Technical Support​

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

Next Steps​