Seamless Wallet Transaction Flow

This guide explains how Seamless Wallet integration works, when each API request is triggered, and what your system needs to do in response.

How Seamless Wallet Works

In Seamless Wallet integrations, the EvenBet system does not store player funds. Instead, every time money needs to be withdrawn or deposited, our system makes a callback request to your server. Your system remains the single source of truth for player balances.

Transaction Flow Diagram

When Each API is Called

Balance Request

Triggered when:

• User enters the system or starts a session

What your system does:

• Return the player's current balance
• No balance changes occur

Example:

// Request
{
  "method": "GetBalance",
  "userId": "123456",
  "currency": "USD"
}

// Response
{
  "balance": 50000,
  "errorCode": 0
}

Casino Integration

This request will include clientId and sessionId as mandatory parameters.

---

Withdrawal Request

Triggered when:

• Player sits at a cash game table (buy-in)
• Player places a bet in a casino game

What your system does:

1. Validate the request signature and parameters
2. Check if this transactionId was already processed (idempotency)
3. Verify player has sufficient funds
4. Debit the amount from player's account
5. Return the new balance

Example - Table buy-in:

// Request
{
  "method": "GetCash",
  "userId": "123456",
  "amount": 15000,
  "currency": "USD",
  "transactionId": "123456789"
}

// Response
{
  "balance": 35000,
  "errorCode": 0
}

Example - Tournament entry:

// Request
{
  "method": "GetCash",
  "userId": "123456",
  "amount": 5500,
  "currency": "USD",
  "transactionId": "123456791",
  "tournamentBuyIn": 5000,
  "tournamentEntryFee": 500
}

Casino Integration

This request will include gameId, betType, and roundId as mandatory parameters.

---

Deposit Request

Triggered when:

• Player stands up from a table (returning chips)
• Player wins in a casino game

What your system does:

1. Validate the request signature and parameters
2. Check if this transactionId was already processed (idempotency)
3. Credit the amount to player's account
4. Return the new balance

Example - Leaving table:

// Request
{
  "method": "ReturnCash",
  "userId": "123456",
  "amount": 23000,
  "currency": "USD",
  "transactionId": "123456791",
  "linkedTransactionIds": ["123456789"],
  "result": 8000,
  "sumOfBets": 45000,
  "rake": 350
}

// Response
{
  "balance": 58000,
  "errorCode": 0
}

Example - Tournament prize:

// Request
{
  "method": "ReturnCash",
  "userId": "123456",
  "amount": 20000,
  "currency": "USD",
  "transactionId": "123456792",
  "transactionType": "prize"
}

Casino Integration

This request will include gameId, winType, and roundId as mandatory parameters.

---

Rollback Request

Triggered when:

• An error occurs while crediting funds to the EvenBet system
• An unrecognizable error is received from your system in response to a Withdrawal Request

What your system does:

1. Validate the request signature and parameters
2. Verify the referenceTransactionId exists
3. Verify the amount, currency, and userId match the original transaction
4. Reverse the original transaction (credit back what was debited)
5. Return the new balance

Example:

// Request
{
  "method": "Rollback",
  "userId": "123456",
  "amount": 15000,
  "currency": "USD",
  "transactionId": "123456793",
  "referenceTransactionId": "123456789"
}

// Response
{
  "balance": 50000,
  "errorCode": 0
}

Casino Integration

This request will include gameId and roundId as mandatory parameters.

---

Important Concepts

Idempotency

Your system must handle duplicate requests gracefully. If you receive a request with a transactionId you've already processed:

1. Do NOT process the transaction again
2. Return errorCode: 0 with the comment "Transaction already processed"
3. Return the current balance and all other required parameters

This prevents double-charging or double-crediting players if a request is retried.

Example:

// Second request with same transactionId
{
  "balance": 35000,
  "errorCode": 0,
  "errorDescription": "Transaction already processed"
}

Retry Behavior

Different requests have different retry logic:

Request Type	Retry Behavior
Balance Request	No retry
Withdrawal Request	Configurable (default: 1 retry after 1 second on timeout/server error)
Deposit Request	Retries every 30 seconds for 2 days
Rollback Request	No retry

When requests are retried:

• Timeout occurs when attempting to make a request
• Server-side error (4xx, 5xx status codes)
• Response cannot be interpreted (invalid JSON, missing errorCode)

When requests are NOT retried:

• Valid error response is received (proper JSON with errorCode)

Transaction States (Deposit Request Only)

Deposit requests can have special states:

Stopped

• Occurs when: Player is blocked
• Behavior: Transaction is stopped and will not be processed
• Resolution: Can be restarted manually from Backoffice in External Transactions section

Delayed

• Occurs when: Transaction amount exceeds configured threshold (optional feature, disabled by default)
• Behavior: Transaction execution is delayed by 30 seconds
• Process:
  1. ReturnCash event received
  2. Amount exceeds threshold X
  3. Status set to "delayed"
  4. System waits 30 seconds
  5. Status changes to "created"
  6. Transaction executes normally

Validation Rules

Your system must validate every request according to these rules:

For all requests:

1. All mandatory parameters must be present → Return error "Invalid request params" if missing
2. Request signature must match → Return error "Invalid signature" if mismatch
3. userId must exist → Return error "Player not found" if not found
4. currency must be a valid ISO code → Return error "Invalid request params" if invalid

For Withdrawal and Deposit requests:

5. amount must be a positive integer or zero → Return error "Invalid request params" if negative
6. If transactionId already processed → Return errorCode: 0 with "Transaction already processed"

For Withdrawal requests only:

7. Player must have sufficient funds → Return error "Insufficient funds" if balance too low

For Rollback requests:

8. referenceTransactionId must exist → Return error "Reference transaction does not exist"
9. amount, currency, and userId must match reference transaction → Return error "Reference transaction has incompatible data"

See Error Reference for complete error code list.

Error Response Format

If "Transaction already processed" or "Insufficient funds": Return ALL response parameters including balance.

For all other errors: Return ONLY errorCode and errorDescription parameters.

// Other errors - minimal response
{
  "errorCode": 2,
  "errorDescription": "Player not found"
}

Casino Integration

All requests require the Content-Type: application/json header in addition to the signature header. The clientId parameter is passed in all requests, and sessionId is mandatory (not optional).

---

Complete Transaction Examples

Scenario 1: Successful Cash Game Session

1. Player logs in
   • Balance Request → Response: $500.00
2. Player sits at table with $150 buy-in
   • Withdrawal Request (transactionId: "123456789", amount: 15000) → Response: $350.00
3. Player plays for 30 minutes
4. Player leaves table with $230
   • Deposit Request (transactionId: "123456790", amount: 23000, linkedTransactionIds: "123456789") → Response: $580.00

Scenario 2: Failed Withdrawal with Rollback

1. Player attempts to buy-in for $200
   • Withdrawal Request (transactionId: "123456792", amount: 20000) → Your system: Debit $200
2. Error occurs in EvenBet system during crediting
3. System initiates rollback
   • Rollback Request (transactionId: "123456793", referenceTransactionId: "123456792", amount: 20000) → Your system: Credit $200 back

Scenario 3: Multiple Table Sessions

1. Player sits at first table with $150
   • Withdrawal Request (transactionId: "123456794", amount: 15000) → Response: $350.00
2. Player leaves first table with $200
   • Deposit Request (transactionId: "123456795", amount: 20000) → Response: $550.00
3. Player sits at second table with $100
   • Withdrawal Request (transactionId: "123456796", amount: 10000) → Response: $450.00
4. Player leaves second table with $175
   • Deposit Request (transactionId: "123456797", amount: 17500) → Response: $625.00

---

Next Steps

Now that you understand the transaction flow, refer to the individual API reference pages for detailed parameter specifications:

• Balance Request - GetBalance method
• Withdrawal Request - GetCash method
• Deposit Request - ReturnCash method
• Rollback Request - Rollback method
• Error Reference - Complete error code list