Wallet API

Wallet API Reference - Operator API

Wallet API is an API to integrate Seamless wallet logic to Bingão. The API works in a manner where Bingão is the consumer and the Operator needs to provide corresponding endpoints based on the following API structures.

Retrieves the current wallet balance for a player.

post

Returns real-time balance information by validating game access and retrieving data from the Inventory service.

Process Flow:

1. Validate player session and game code format

2. Extract room ID from game code (format: "BINGAO_{roomId}")

3. Verify game availability via Room Manager

4. Retrieve current balance from Inventory service

Requirements:

• Valid X-Player-Token header

• Game code in format "BINGAO_{roomId}"

• Supported currency (ISO 4217)

Sample request:

{
    "gameCode": "BINGAO_550e8400-e29b-41d4-a716-446655440000",
    "currency": "BRL"
}

Sample response:

{
    "player": "550e8400-e29b-41d4-a716-446655440000",
    "status": "RS_OK",
    "currency": "BRL",
    "balance": "1250.50"
}

Authorizations

Bearer

AuthorizationstringRequired

REQUIRED - JWT Authorization header using the Bearer scheme. All API endpoints require authentication, except for authentication endpoints (Connect/authentication). Example: "Authorization: Bearer {token}"

Query parameters

api-versionstringOptional

Header parameters

X-Player-TokenstringOptional

Player access token for session validation

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

application/jsontext/jsonapplication/*+json

gameCodestring · nullableOptional

currencystring · nullableOptional

Responses

200

Successfully retrieved player balance with current amount and currency information.

text/plainapplication/jsontext/json

playerstring · nullableOptional

statusstring · nullableOptional

currencystring · nullableOptional

balancestring · nullableOptional

400

Invalid request data, malformed game code, unsupported currency, or player validation failure.

text/plainapplication/jsontext/json

401

Invalid or missing X-Player-Token header authentication.

text/plainapplication/jsontext/json

post

/wallet/player/balance

HTTPcURLJavaScriptPython

POST /wallet/player/balance HTTP/1.1
Host: operator-api.mgm.bingaodobrasil.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "gameCode": "text",
  "currency": "text"
}

application/jsontext/jsonapplication/*+json

{
  "player": "text",
  "status": "text",
  "currency": "text",
  "balance": "text"
}

Processes a BET transaction (debit) on the player's wallet.

post

Debits the player's account with bet amount after validating game access and player session.

Process Flow:

1. Validate player session and authentication token

2. Extract and validate transaction ID from headers

3. Verify game code format (format: "BINGAO_{roomId}")

4. Check game availability via Room Manager

5. Process debit transaction via Inventory service

6. Apply idempotency checks to prevent duplicate debits

Requirements:

• Valid X-Player-Token header for authentication

• Valid X-Transaction-Id header (GUID format) for idempotency

• Game code in format "BINGAO_{roomId}"

• Supported currency (ISO 4217)

• Positive amount value

• Sufficient balance in player account

Idempotency:

• Re-sending the same X-Transaction-Id with identical body returns the same result (200 OK)

• Re-sending the same X-Transaction-Id with a different body returns 409 Conflict

Sample request:

{
    "gameCode": "BINGAO_550e8400-e29b-41d4-a716-446655440000",
    "currency": "BRL",
    "amount": 50.00
}

Important:

• This endpoint does not return the updated balance

• Use /wallet/player/balance to retrieve the current balance after processing

• Amount is debited as provided (decimal precision maintained)

• Transaction will fail if player has insufficient balance

Authorizations

Bearer

AuthorizationstringRequired

REQUIRED - JWT Authorization header using the Bearer scheme. All API endpoints require authentication, except for authentication endpoints (Connect/authentication). Example: "Authorization: Bearer {token}"

Query parameters

api-versionstringOptional

Header parameters

X-Transaction-Idstring · uuidOptional

Unique transaction identifier for request tracking

Example: fd694e40-753f-4cdf-9c46-32f80e1b1fb8

X-Player-TokenstringOptional

Player access token for session validation

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

application/jsontext/jsonapplication/*+json

gameCodestring · nullableOptional

currencystring · nullableOptional

amountnumber · doubleOptional

Responses

200

Bet transaction successfully processed and debited from player account.

No content

400

Invalid request data, malformed game code, unsupported currency, invalid amount, insufficient balance, or player validation failure.

text/plainapplication/jsontext/json

401

Invalid or missing X-Player-Token header authentication.

409

Idempotency conflict: same X-Transaction-Id used with different request body.

post

/wallet/transaction/bet

HTTPcURLJavaScriptPython

POST /wallet/transaction/bet HTTP/1.1
Host: operator-api.mgm.bingaodobrasil.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "gameCode": "text",
  "currency": "text",
  "amount": 1
}

application/jsontext/jsonapplication/*+json

No content

Processes a WIN transaction (credit) for the player's wallet.

post

Credits the player's account with winning amount after validating game access and player session.

Process Flow:

1. Validate player session and authentication token

2. Extract and validate transaction ID from headers

3. Verify game code format (format: "BINGAO_{roomId}")

4. Check game availability via Room Manager

5. Process credit transaction via Inventory service

6. Apply idempotency checks to prevent duplicate credits

Requirements:

• Valid X-Player-Token header for authentication

• Valid X-Transaction-Id header (GUID format) for idempotency

• Game code in format "BINGAO_{roomId}"

• Supported currency (ISO 4217)

• Positive amount value

Idempotency:

• Re-sending the same X-Transaction-Id with identical body returns the same result (200 OK)

• Re-sending the same X-Transaction-Id with a different body returns 409 Conflict

Sample request:

{
    "gameCode": "BINGAO_550e8400-e29b-41d4-a716-446655440000",
    "currency": "BRL",
    "amount": 125.50
}

Important:

• This endpoint does not return the updated balance

• Use /wallet/player/balance to retrieve the current balance after processing

• Amount is credited as provided (decimal precision maintained)

Authorizations

Bearer

AuthorizationstringRequired

REQUIRED - JWT Authorization header using the Bearer scheme. All API endpoints require authentication, except for authentication endpoints (Connect/authentication). Example: "Authorization: Bearer {token}"

Query parameters

api-versionstringOptional

Header parameters

X-Transaction-Idstring · uuidOptional

Unique transaction identifier for request tracking

Example: 7881704e-f897-45f8-820b-9929e687a17f

X-Player-TokenstringOptional

Player access token for session validation

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

application/jsontext/jsonapplication/*+json

gameCodestring · nullableOptional

currencystring · nullableOptional

amountnumber · doubleOptional

Responses

200

Win transaction successfully processed and credited to player account.

No content

400

Invalid request data, malformed game code, unsupported currency, invalid amount, or player validation failure.

text/plainapplication/jsontext/json

401

Invalid or missing X-Player-Token header authentication.

409

Idempotency conflict: same X-Transaction-Id used with different request body.

post

/wallet/transaction/win

HTTPcURLJavaScriptPython

POST /wallet/transaction/win HTTP/1.1
Host: operator-api.mgm.bingaodobrasil.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "gameCode": "text",
  "currency": "text",
  "amount": 1
}

application/jsontext/jsonapplication/*+json

No content

Retrieves a paginated list of betting transactions grouped by rounds.

get

Returns betting transaction history with round-based grouping and optional filtering by session or round.

Features:

• Transactions grouped by round ID for better organization

• Optional filters: sessionId and roundId

• Pagination support (default: page 1, size 10)

• Only returns BET type transactions

• Player-scoped results (authenticated player only)

Response Format:

• JSON with camelCase naming

• Indented formatting for readability

• Null values excluded

Sample request:

GET /api/v1/wallet/transaction/bet?pageNumber=1&pageSize=20&sessionId=550e8400-e29b-41d4-a716-446655440000

Sample response:

{
    "roundId": "round_550e8400-e29b-41d4-a716-446655440000",
    "transactions": [
        {
            "transactionId": "txn_123456789",
            "amount": "25.50",
            "currency": "BRL",
            "timestamp": "2024-01-15T14:30:00Z",
            "type": "bet"
        }
    ]
}

Authorizations

Bearer

AuthorizationstringRequired

REQUIRED - JWT Authorization header using the Bearer scheme. All API endpoints require authentication, except for authentication endpoints (Connect/authentication). Example: "Authorization: Bearer {token}"

Query parameters

pageNumberinteger · int32Optional

The page number for pagination (1-based indexing). Controls which page of results to return. Default value is 1.

Default: 1

pageSizeinteger · int32Optional

The number of transaction groups per page. Controls response size and performance. Default value is 10, recommended range 1-100.

Default: 10

sessionIdstring · uuidOptional

Optional game session identifier (GUID format) to filter transactions by specific gaming session. When provided, only transactions from the specified session are returned.

roundIdstring · uuidOptional

Optional round identifier (GUID format) to filter transactions by specific game round. When provided, only transactions from the specified round are returned.

api-versionstringOptional

Header parameters

X-Player-TokenstringOptional

Player access token for session validation

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses

200

Successfully retrieved paginated betting transactions with round-based grouping and applied filters.

text/plainapplication/jsontext/json

playerIdstring · uuidOptional

pageinteger · int32Optional

limitinteger · int32Optional

400

Invalid request parameters, malformed GUIDs, invalid pagination values, or missing player authentication.

text/plainapplication/jsontext/json

401

Invalid or missing X-Player-Token header authentication.

text/plainapplication/jsontext/json

404

No betting transactions found for the specified filtering criteria.

text/plainapplication/jsontext/json

get

/wallet/transaction/bet

HTTPcURLJavaScriptPython

GET /wallet/transaction/bet HTTP/1.1
Host: operator-api.mgm.bingaodobrasil.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "playerId": "123e4567-e89b-12d3-a456-426614174000",
  "bets": [
    {
      "roundId": "123e4567-e89b-12d3-a456-426614174000",
      "sessionId": "123e4567-e89b-12d3-a456-426614174000",
      "bets": [
        {
          "transactionId": "123e4567-e89b-12d3-a456-426614174000",
          "timestamp": "2026-03-02T02:43:36.145Z",
          "betAmount": 1,
          "gameId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1
}

Retrieves a paginated list of winning transactions grouped by rounds.

get

Returns winning transaction history with round-based grouping and optional filtering by session or round.

Features:

• Win transactions grouped by round ID

• Optional filters: sessionId and roundId

• Pagination support (default: page 1, size 10)

• Only returns WIN type transactions

• Player-scoped results (authenticated player only)

• Includes regular wins, bonuses, and jackpots

Response Format:

• JSON with camelCase naming

• Indented formatting for readability

• Null values excluded

Sample request:

GET /api/v1/wallet/transaction/win?pageNumber=1&pageSize=25&sessionId=550e8400-e29b-41d4-a716-446655440000

Sample response:

{
    "roundId": "round_550e8400-e29b-41d4-a716-446655440000",
    "winTransactions": [
        {
            "transactionId": "win_txn_987654321",
            "amount": "125.75",
            "currency": "BRL",
            "timestamp": "2024-01-15T14:32:15Z",
            "type": "win"
        }
    ]
}

Authorizations

Bearer

AuthorizationstringRequired

REQUIRED - JWT Authorization header using the Bearer scheme. All API endpoints require authentication, except for authentication endpoints (Connect/authentication). Example: "Authorization: Bearer {token}"

Query parameters

pageNumberinteger · int32Optional

The page number for pagination (1-based indexing). Controls which page of win results to return. Default value is 1.

Default: 1

pageSizeinteger · int32Optional

The number of win transaction groups per page. Controls response size and performance. Default value is 10, recommended range 1-100.

Default: 10

sessionIdstring · uuidOptional

Optional game session identifier (GUID format) to filter win transactions by specific gaming session. When provided, only win transactions from the specified session are returned.

roundIdstring · uuidOptional

Optional round identifier (GUID format) to filter win transactions by specific game round. When provided, only win transactions from the specified round are returned.

api-versionstringOptional

Header parameters

X-Player-TokenstringOptional

Player access token for session validation

Example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses

200

Successfully retrieved paginated winning transactions with round-based grouping and applied filters.

text/plainapplication/jsontext/json

playerIdstring · uuidOptional

pageinteger · int32Optional

limitinteger · int32Optional

400

Invalid request parameters, malformed GUIDs, invalid pagination values, or missing player authentication.

text/plainapplication/jsontext/json

401

Invalid or missing X-Player-Token header authentication.

text/plainapplication/jsontext/json

404

No winning transactions found for the specified filtering criteria.

text/plainapplication/jsontext/json

get

/wallet/transaction/win

HTTPcURLJavaScriptPython

GET /wallet/transaction/win HTTP/1.1
Host: operator-api.mgm.bingaodobrasil.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "playerId": "123e4567-e89b-12d3-a456-426614174000",
  "wins": [
    {
      "roundId": "123e4567-e89b-12d3-a456-426614174000",
      "sessionId": "123e4567-e89b-12d3-a456-426614174000",
      "roundCompleted": true,
      "wins": [
        {
          "transactionId": "123e4567-e89b-12d3-a456-426614174000",
          "timestamp": "2026-03-02T02:43:36.145Z",
          "winAmount": 1,
          "gameId": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
  ],
  "page": 1,
  "limit": 1
}

Processes a ROLLBACK transaction to reverse a previously processed BET transaction.

post

Reverts a BET transaction by crediting back the original bet amount to the player's account after validating transaction integrity.

Process Flow:

1. Extract and validate rollback transaction ID from headers

2. Retrieve original BET transaction by transaction ID from request body

3. Verify transaction exists and is of type BET

4. Verify rollback amount matches original BET amount

5. Check if transaction was already rolled back

6. Process rollback credit via Inventory service

7. Apply idempotency checks to prevent duplicate rollbacks

Requirements:

• Valid X-Transaction-Id header (GUID format) for idempotency

• Request body must contain the original BET transaction ID to be rolled back

• Referenced transaction must exist and be of type BET

• Rollback amount must exactly match original BET amount

• Transaction cannot have been previously rolled back

• Supported currency (ISO 4217)

Idempotency:

• Re-sending the same X-Transaction-Id with identical body returns the same result (200 OK)

• Re-sending the same X-Transaction-Id with a different body returns 409 Conflict

Sample request:

{
    "transactionId": "550e8400-e29b-41d4-a716-446655440001",
    "amount": 50.00,
    "currency": "BRL"
}

Important:

• This endpoint does not return the updated balance

• Use /wallet/player/balance to retrieve the current balance after processing

• Amount must exactly match the original BET amount

• Once rolled back, the same transaction cannot be rolled back again

Authorizations

Bearer

AuthorizationstringRequired

REQUIRED - JWT Authorization header using the Bearer scheme. All API endpoints require authentication, except for authentication endpoints (Connect/authentication). Example: "Authorization: Bearer {token}"

Query parameters

api-versionstringOptional

Header parameters

X-Transaction-Idstring · uuidOptional

Unique transaction identifier for request tracking

Example: 1417156b-f533-4ac1-bb37-99d5d9a35197

Body

application/jsontext/jsonapplication/*+json

transactionIdstring · uuidOptional

amountnumber · doubleOptional

currencystring · nullableOptional

Responses

200

Rollback transaction successfully processed and amount credited back to player account.

No content

400

Invalid request data, transaction not found, transaction is not a BET type, amount mismatch, or transaction already rolled back.

text/plainapplication/jsontext/json

404

Referenced transaction ID not found in the system.

text/plainapplication/jsontext/json

409

Idempotency conflict: same X-Transaction-Id used with different request body.

post

/wallet/transaction/rollback

HTTPcURLJavaScriptPython

POST /wallet/transaction/rollback HTTP/1.1
Host: operator-api.mgm.bingaodobrasil.com.br
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 85

{
  "transactionId": "123e4567-e89b-12d3-a456-426614174000",
  "amount": 1,
  "currency": "text"
}

application/jsontext/jsonapplication/*+json

No content