Skip to main content

Operator API Implementation Guide

In Seamless Wallet Mode, Operator needs to implement a unified API for VP to call, to achieve Balance query, Bet Settlement, and transaction processing.

Architecture Overview​

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

API Implementation Description​

Operator needs to provide a set of callback URLs on its own server. Operator needs to decide the operation to perform based on the action parameter in the request:

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

Unified URL​

Operator only needs 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 parameters of the request to distinguish different operations

Implementation Requirements​

1. Security Requirements​

  • ✅ Encrypted Transmission: All request content uses AES-256-GCM encryption, responses use plaintext 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

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 which will be considered a timeout

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, and 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. After Player closes Games or logs out, the Token should be invalidated.

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

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

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; they will continue to retry 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 configured and verified via the backend.

Technical Support​

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

Next Steps​