Skip to main content

Operator API Implementation Description

Under 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 and process transactions with the Operator.

API Implementation Description​

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

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

Unified URL​

The Operator only needs to provide a single callback URL, for example:

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

VP will include the action Field in the decrypted request parameters to differentiate between different operations

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 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

The response format for all Operator APIs is unified as plaintext JSON, with the fixed format as follows:

{
  "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

FAQ​

Q1: How to differentiate between different operations?​

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

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

A: Recommended 24 hours. The Token should be invalidated after the Player closes the game or logs out.

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

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

Q4: After how long will a transaction be considered a timeout?​

A: 3 seconds

Q5: Which transactions will enter the Bet retry process?​

A: Transactions for Items and Operator Cards will not Trigger Bet cancellation; instead, 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 transaction callback URL; it can be specifically set and verified through the backend.

Technical Support​

If you encounter problems during the implementation process, please Contact Customer Support Team

Next Steps​