Skip to main content

Operator API Implementation Guide

In Seamless Wallet Mode, the Operator needs to implement a unified API for VP to call, in order to handle Balance queries, 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 the Balance from the Operator and process transactions.

API Implementation Description​

The Operator needs to provide one set of callBack URLs on its own server. The Operator must determine which operation to execute 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 Endpoint​

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

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

VP will include an action field in the decrypted request parameters to distinguish between different operations.

Unified Request Header Content​

FieldTypeDescription
x-agentidstringThe agent this transaction belongs to
x-custom-system-trace-idstringTransaction trace code, in UUID format

Implementation Requirements​

1. Security Requirements​

  • ✅ Encrypted Transmission: All request content is encrypted with 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

All Operator API responses use a unified plaintext JSON format, as follows:

{
  "status": "0000",
  "errText": "",
  "balance": 12345.67,
  "responseTime": "2024-12-11T01:23:38.271Z"
}
FieldTypeDescription
statusstringStatus code, see each API's description for details
errTextstringError message, empty string when successful
balancenumberPlayer's Balance after the operation
responseTimestringResponse time

3. Performance Requirements​

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

FAQ​

Q1: How to distinguish between different operations?​

A: VP will include an 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 to?​

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 support?​

A: Support up to 4 decimal places (0.0001), with a minimum of 2 decimal places (0.01).

Q4: After how long is a transaction considered a timeout?​

A: 3 seconds

Q5: Which transactions enter the Bet retry process?​

A: Transactions involving Items and Operator Cards will not trigger a Bet cancellation; they will continue to be retried via the "Bet Retry" API.

Q6: Can the callBack Url be adjusted?​

A: Yes. We do not specify any particular format for the callBack Url used for transaction responses; it can be configured and verified via the admin backend.

Technical Support​

If you encounter any issues during implementation, please contact the Customer Support Team and include the UUID from the Headers to facilitate issue tracking.

Next Steps​