The wallet model determines where balance authority lives, how money-changing operations cross system boundaries, and which failures the integration must recover from. The choice should follow the platform's existing ledger and operating model.
Last reviewed: 2026-08-09
| Question | Single wallet | Transfer wallet |
|---|---|---|
| Primary balance authority | The merchant platform normally keeps the unified player balance. | Funds move between the merchant side and a game wallet according to the agreed workflow. |
| Main integration direction | The game platform calls merchant wallet callbacks during play. | The merchant calls deposit, withdrawal, balance, and transaction endpoints. |
| Main reliability concern | Callback latency, idempotent processing, and returning a consistent resulting balance. | Transfer-state uncertainty, duplicate transfer prevention, and balance-to-ledger reconciliation. |
| Operational evidence | Callback logs, transaction identity, resulting balance, and game records. | Merchant ledger entries, transfer records, wallet balance, and recovery actions. |
| Typical architecture question | Can the existing wallet safely serve synchronous external callbacks? | Can the existing platform manage a separate game-wallet lifecycle? |
Neither model is automatically simpler. A single wallet may require low-latency and highly available callbacks; a transfer wallet may require more explicit movement and recovery controls.
- Which system owns the authoritative balance before and after a callback?
- How is one bet, settlement, or cancellation identified across retries?
- Can the same transaction be processed safely more than once?
- What response is returned when the original outcome is already known?
- Which redacted logs can both teams use through the support workflow?
- How will the platform degrade or stop sessions when its wallet is unavailable?
- What event initiates a deposit or withdrawal?
- How does the merchant ledger represent pending, successful, failed, and uncertain transfers?
- What happens when a request times out after the receiving system may have processed it?
- How are remaining funds recovered when a session ends unexpectedly?
- Which transaction query is used before retrying a money-moving operation?
- How are wallet balances and transaction records reconciled with the merchant ledger?
- Draw the current player balance and ledger flow before adding the game integration.
- Identify which system may create or finalize a money-changing record.
- Model a success, timeout, duplicate request, delayed callback, and partial outage.
- Compare both the happy-path implementation and the operational recovery effort.
- Map the endpoint and callback set to the selected wallet architecture.
- Freeze the chosen responsibility matrix before implementation.
Continue with the integration workflow after the wallet responsibility is understood.