Skip to main content

Operator API Implementation Guide

In Seamless Wallet Mode, the Operator needs to implement a unified API for the 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. The VP, as the Games 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 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​

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

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

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

Unified Request Header Content​

FieldTypeDescription
x-agentidstringThe Agent ID associated with this transaction
x-custom-system-trace-idstringTransaction trace code, UUID format

Implementation Requirements​

1. Security Requirements​

  • ✅ Encrypted Transmission: All request content is encrypted using AES-256-GCM, and responses use plain JSON format
  • ✅ HTTPS: Production environment must use HTTPS
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 plain 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 the operation
responseTimestringResponse time

3. Performance Requirements​

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

FAQ​

Q1: How to distinguish different operations?​

A: The 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: Up to 4 decimal places (0.0001) are supported; at least 2 decimal places (0.01) must be supported.

Q4: How long until a transaction is considered a timeout?​

A: 3 seconds

Q5: Which transactions enter the Bet retry process?​

A: Transactions for Items and Operator Cards will not trigger a 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 in transactions. It can be configured and verified via the backend.

Technical Support​

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

Next Steps​