Skip to content

Wallet API Specification

This section defines the RESTful API that the Operator must implement to handle wallet transactions from Flex-Soft.

Overview

Flex-Soft follows a standard server-to-server integration model. The Flex-Soft platform sends HTTP POST requests to your (the Operator's) backend to authorize players, place bets, and settle wins.

  • Protocol: HTTP/1.1 or HTTP/2
  • Format: JSON
  • Requests: Initiated by Flex-Soft -> Operator

Data Types & Currency

All monetary values in this API are integers represented in millis (1/1000th of the main currency unit).

  • Formula: Amount in Millis = Amount in Unit * 1000
  • Example: 5.44 USD -> 5440 (millis)
  • Example: 1.00 EUR -> 1000 (millis)

[!CAUTION] Do not use floating point numbers. Always send integers.

Idempotency (Best Practice)

Network failures can occasionally cause Flex-Soft to send the same request multiple times (e.g., a timeout occurs before we receive your response).

To prevent double-charging or double-crediting players, your Wallet API MUST implement idempotency.

  • Idempotency Key: Use the provider_tx_id field in the request body.
  • Logic:
    1. Check if a transaction with this provider_tx_id already exists in your system.
    2. If it exists, return the original response immediately (do not process the balance change again).
    3. If it does not exist, process the transaction and save the result.

[!TIP] This is critical for BET (Withdraw) and WIN (Deposit) endpoints to ensure player balances remain accurate even during network instability.

Security

Every request from Flex-Soft includes the following headers for security verification:

Header Description
X-Public-Key Your assigned public key. Use this to identify the tenant.
X-Signature HMAC SHA256 signature of the request body using your Secret Key.

[!IMPORTANT] You MUST verify the X-Signature on every request. Compute the HMAC SHA256 of the raw request body using your Secret Key and compare it with the header value.

View Code Samples for Signature Validation (Java, C#, Go, Python)

Endpoints

1. Authentication Check

Verifies the player's session and retrieves their balance.

  • URL: {WALLET_BASE_URL}/auth
  • Method: POST

Request Payload

{
  "user_token": "player123",
  "session_token": "sess-abc-123",
  "platform": "mobile",
  "currency": "USD"
}

Response Payload

{
  "code": 200,
  "message": "OK",
  "data": {
    "user_id": "player123",
    "username": "Player One",
    "balance": 10000000,
    "currency": "USD",
    "maxbet": 5000000
  }
}

2. Withdraw (Bet)

Deducts funds from the player's wallet.

  • URL: {WALLET_BASE_URL}/withdraw
  • Method: POST

Request Payload

{
  "currency": "USD",
  "amount": 5440,
  "provider": "Flex-Soft",
  "provider_tx_id": "tx-1001",
  "game": "chicken-race",
  "action": "BET",
  "action_id": "round-555",
  "session_token": "sess-abc-123",
  "platform": "mobile",
  "user_id": "player123",
  "attributes": []
}

Response Payload

{
  "code": 200,
  "message": "Success",
  "data": {
    "user_id": "player123",
    "operator_tx_id": "op-tx-999",
    "provider_tx_id": "tx-1001",
    "old_balance": 10005440,
    "new_balance": 10000000,
    "currency": "USD"
  }
}

3. Deposit (Win)

Adds funds to the player's wallet.

  • URL: {WALLET_BASE_URL}/deposit
  • Method: POST

Request Payload

{
  "currency": "USD",
  "amount": 1000,
  "provider": "Flex-Soft",
  "provider_tx_id": "tx-1002",
  "withdraw_provider_tx_id": "tx-1001",
  "game": "chicken-race",
  "action": "WIN",
  "action_id": "round-555",
  "session_token": "sess-abc-123",
  "platform": "mobile",
  "user_id": "player123",
  "attributes": []
}

Response Payload

{
  "code": 200,
  "message": "Success",
  "data": {
    "user_id": "player123",
    "operator_tx_id": "op-tx-1000",
    "provider_tx_id": "tx-1002",
    "old_balance": 9500,
    "new_balance": 10500,
    "currency": "USD"
  }
}

4. Get Balance

Retrieves the current balance of the player.

  • URL: {WALLET_BASE_URL}/balance
  • Method: POST

Request Payload

{
  "user_id": "player123",
  "session_token": "sess-abc-123"
}

Response Payload

{
  "currency": "USD",
  "amount": 10500
}

5. Action Types

The action field in Withdraw and Deposit requests indicates the nature of the transaction.

Action API Description
BET Withdraw Standard real-money bet.
WIN Deposit Standard real-money win.
FREE_BET Withdraw Bet using a gift/bonus. Amount should be 0.
FREE_BET_WIN Deposit Win resulting from a free bet.

[!NOTE] For FREE_BET actions, you should verify the player is eligible but do not deduct funds from their main balance.

Error Codes

Code Description
200 Success
400 Bad Request / Validation Error
401 Unauthorized (Invalid Signature or Token)
402 Insufficient Funds
500 Internal Server Error