Skip to main content

Seamless Wallet Overview

Ruby supports two wallet integration modes for brands: Seamless and Transfer. This page explains the difference and helps you decide which mode is right for your platform.

Wallet Modes​

Transfer Mode​

In Transfer mode, Ruby maintains an internal pre-funded wallet for each player. When a player starts a game session, funds are transferred from your brand wallet into Ruby's internal system. Wins and losses are settled within Ruby's wallet, and you reconcile the balance periodically.

Characteristics:

  • No callback endpoints required on your side
  • Simpler integration — no server-side implementation needed
  • Balance is managed by Ruby; your platform queries Ruby for the current balance
  • Suited for operators who want a low-complexity integration or are running on pre-paid credit models

Seamless Mode​

In Seamless mode, Ruby does not maintain any internal player wallet. Instead, every balance-affecting game event triggers a real-time HTTP callback to your server. Your platform's wallet remains the single source of truth for player funds at all times.

Characteristics:

  • Real-time callbacks for every game event (bet, win, rollback)
  • Your server must implement four callback endpoints (see Callback Specification)
  • Player balances are always live — no reconciliation lag
  • Suited for operators who want full control over their wallet system and real-time balance visibility

Choosing a Mode​

ConsiderationTransferSeamless
Integration complexityLowMedium
Wallet ownershipRubyYour platform
Real-time balanceNo (periodic sync)Yes
Callback endpoints requiredNoYes
Uptime dependencyLowerHigher — your callback server must be available
Suited forSimple or pre-paid integrationsOperators with existing wallet infrastructure

If your platform already manages player balances and you want real-time fund accuracy, choose Seamless. If you prefer a lighter integration with no server-side callback requirements, choose Transfer.

How Seamless Mode Works​

The following sequence describes what happens during a typical game round in Seamless mode:

Player action (e.g., place a bet)
        │
        ▼
  Game Provider Server
        │
        │  Game event (bet/win/void)
        ▼
  Ruby Platform
        │
        │  POST {callback_url}/debit   ← Ruby calls your server
        ▼
  Your Wallet Server
        │
        │  { balance, balance_before }
        ▼
  Ruby Platform
        │
        │  Returns result to game provider
        ▼
  Game Provider Server

Step by step:

  1. A player performs an action in a game (places a bet, wins, or the round is voided).
  2. The game provider sends the event to Ruby's platform.
  3. Ruby translates the event into a wallet callback and calls the appropriate endpoint on your callback_url:
    • Bet → POST {callback_url}/debit (funds removed from player wallet)
    • Win/Settlement → POST {callback_url}/credit (funds added to player wallet)
    • Void/Rollback → POST {callback_url}/rollback (reverse a prior debit)
    • Balance query → POST {callback_url}/balance (stateless read, no funds moved)
  4. Your server processes the request, updates your wallet, and returns the new balance.
  5. Ruby uses the returned balance to complete the game provider flow.

All four callbacks are authenticated using HMAC-SHA256 signatures. See Callback Authentication for the verification details.

Requirements for Seamless Integration​

Before going live with Seamless mode, ensure your implementation meets the following requirements:

Endpoint Availability​

  • You must implement all four callback endpoints: /balance, /debit, /credit, /rollback
  • Your callback server must be reachable from Ruby's servers over HTTPS
  • Your callback_url must not have a trailing slash (e.g., https://wallet.example.com/ruby not https://wallet.example.com/ruby/)

Performance​

  • Hard timeout: Ruby will abort any callback that does not respond within 5 seconds
  • Recommended response time: under 3 seconds to provide headroom before the hard cutoff
  • Slow responses cause game errors for players — treat callback latency as a critical metric

Idempotency​

  • The /debit, /credit, and /rollback endpoints must be idempotent
  • Use transaction_id to detect duplicate requests and return the original result without re-processing
  • The /balance endpoint is a stateless read and does not require idempotency handling

Signature Verification​

  • Verify the X-Aggregator-Signature header on every incoming callback request
  • Reject requests with invalid signatures, expired timestamps, or unknown API keys
  • See Callback Authentication for the full verification algorithm

Error Handling​

  • Return a non-2xx HTTP status code if the transaction cannot be processed (e.g., insufficient funds, player not found)
  • Ruby treats any 2xx status as success. Non-2xx responses propagate as errors to the game provider
  • There is currently no automatic retry mechanism — a failed callback results in an immediate error

Next Steps​