To migrate player wallets without breaking casino balances, move the ledger state behind each balance, preserve every transaction and wallet state, reconcile the source and target systems player by player, and cut over only after both sides match. Do not simply copy the visible balance from the old platform into the new one.
That sounds obvious until you look at what a single balance can contain.
A player showing $250 in the old casino may actually have:
$180 available cash
$40 locked in a pending withdrawal
$20 in active bonus funds
$10 tied to an unsettled game round
If the new platform only receives a balance = 250.00, the migration can look successful while the financial state underneath it is already wrong.
That is why a safe wallet migration follows a stricter pattern:
Map wallet states
→ preserve transaction identity
→ migrate the ledger
→ rebuild balances
→ reconcile both systems
→ capture final changes
→ cut over
If the wallet move is part of a larger replatforming project involving player accounts, KYC, games, payments, and casino operations, How Do You Migrate an Online Casino to a New Platform Safely? covers the wider migration process.
For the wallet itself, start with the ledger, not the number displayed to the player.
Step 1: Map Every Wallet State
Start by mapping the old wallet model to the new one.
Source state
Target state
Action
Available cash
Cash wallet
Move
Bonus balance
Bonus wallet
Transform
Locked funds
Restricted balance
Preserve
Pending withdrawal
Pending payout
Preserve
Reserved wager
Reserved funds
Preserve
Expired bonus
Archive
Do not credit
This catches one of the biggest problems early.
The old system may understand five different forms of money, while the new system only understands two.
If the destination cannot represent something the source wallet stores, you have an architecture problem before you have a migration problem.
Solve that first.
Step 2: Make Every Transaction Safe to Retry
Migration jobs fail.
Workers restart. Connections time out. Batches get retried.
A retry must never credit the same transaction twice.
One simple approach is to preserve the original transaction ID and combine it with the source system.
CREATE TABLE wallet_entries (
id BIGSERIAL PRIMARY KEY,
player_id BIGINT NOT NULL,
source_system TEXT NOT NULL,
source_transaction_id TEXT NOT NULL,
amount NUMERIC(24, 8) NOT NULL,
currency TEXT NOT NULL,
direction TEXT NOT NULL,
status TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL,
UNIQUE (source_system, source_transaction_id)
);
Now the same source transaction cannot silently create another ledger entry when a batch is rerun.
In other words:
Make the migration idempotent.
You should be able to retry a failed batch without changing the financial result.
Step 3: Move the Ledger Before Rebuilding the Balance
If the new platform keeps historical ledger entries, migrate those entries before setting the wallet projection.
Avoid treating this as the migration:
UPDATE wallets
SET balance = source_balance;
Instead, the migrated financial records should explain why the player owns that amount.
A simplified calculation could look like this:
SELECT
player_id,
SUM(
CASE
WHEN direction = 'credit' THEN amount
WHEN direction = 'debit' THEN -amount
END
) AS calculated_balance
FROM wallet_entries
WHERE status = 'posted'
GROUP BY player_id;
Then compare the calculated result with the expected source balance.
Not every platform needs to import years of ledger history into its active database.
Some architectures keep the old transactions in an immutable archive and create a reconciled opening balance in the new ledger.
That is fine too.
What matters is that the opening balance can still be traced back to the financial records that produced it.
Step 4: Reconcile Player by Player
A migration job returning success tells you that records were inserted.
It does not tell you that the money is right.
Build a reconciliation dataset.
player_id
source_cash
target_cash
source_bonus
target_bonus
source_locked
target_locked
difference
status
Then compare at two levels.
Player level
Check:
cash balance
bonus balance
locked balance
pending withdrawals
reserved funds
System level
Check:
total money by currency
transaction counts
total transaction value
total pending withdrawals
total bonus liability
You need both.
Imagine this:
Player A: +$50 error
Player B: -$50 error
Your system-wide total still matches.
Both players are still wrong.
Step 5: Handle Money That Moves During Migration
This is where live wallet migrations become interesting.
Suppose the snapshot is taken at 02:00.
At 02:04, a player deposits $100.
At 02:10, you switch traffic to the dataset created at 02:00.
That deposit now exists in one platform and not the other.
You need a cutover strategy.
Option A: Short Write Freeze
Temporarily stop balance-changing actions.
Take the final delta, reconcile it, and then switch the platform.
This creates a small maintenance window, but the financial model stays relatively simple.
Option B: Delta Capture
Move the large historical dataset first.
Then record the changes that happen afterward.
T0 Initial snapshot
↓
T1 Bulk migration
↓
T2 Capture new transactions
↓
T3 Replay final delta
↓
T4 Reconcile
↓
T5 Cut over
This reduces the final migration window.
Option C: Dual-Write
New transactions are written to both wallet systems for a period.
I would be cautious with this.
You are solving a migration problem by temporarily creating two writable financial systems that now have to agree.
Sometimes that is justified.
Sometimes a short freeze or well-tested delta process is much easier to reason about.
Step 6: Test the Accounts That Look Ugly
Do not validate the migration using ten perfectly normal test players.
Test accounts with:
multiple currencies
pending withdrawals
active bonuses
locked funds
chargebacks
reversed deposits
unsettled game rounds
suspended accounts
duplicate legacy IDs
missing references
very large transaction histories
The clean account proves your happy path works.
The ugly account proves your migration logic works.
Step 7: Decide What Stops the Launch
Do this before cutover.
Not at 3 AM while everyone is staring at a reconciliation dashboard.
A simple go/no-go list might look like:
Wallet balance mismatch -> STOP
Missing pending withdrawal -> STOP
Restricted funds missing -> STOP
Critical payment failure -> STOP
Unreconciled account -> REVIEW
Rollback path unavailable -> STOP
The exact tolerances depend on the platform and operator.
The important part is deciding them before the migration begins.
Otherwise, every problem becomes a debate during the most stressful part of the deployment.
Rollback Gets Hard Once New Money Moves
Application rollback is usually easy to imagine.
Financial rollback is different.
After cutover, players may:
deposit
wager
win
withdraw
receive bonuses
Those events now exist only because the new platform went live.
You cannot simply restore yesterday's database and pretend they never happened.
Your rollback plan therefore needs to answer:
Which system is the source of truth?
What happens to post-cutover transactions?
Can those events be replayed?
How do we prevent duplicate settlement?
At what point do we stop rolling back
and start recovering forward?
That final question matters.
At some point, rollback becomes forward recovery.
My Production Wallet Migration Checklist
If I had to compress the whole migration into one runbook, I would use this:
[ ] Document every wallet state
[ ] Map old states to new states
[ ] Preserve stable transaction IDs
[ ] Migrate or archive historical ledger data
[ ] Import pending financial states
[ ] Rebuild wallet projections
[ ] Reconcile every player
[ ] Reconcile totals by currency
[ ] Test edge-case accounts
[ ] Run the process in staging
[ ] Capture the final production delta
[ ] Reconcile again
[ ] Apply go/no-go rules
[ ] Switch traffic
[ ] Monitor deposits and withdrawals
[ ] Keep an exception queue for mismatches
That is the part I would keep beside the migration dashboard on cutover day.
The Wallet Is Still Only One Part of the Casino
A casino wallet rarely operates alone.
It connects with payment gateways, games, bonuses, KYC, player accounts, reporting, and the back office.
That becomes even more obvious in custom gaming environments. Idea Usher's metaverse casino game development services, for example, involve wallet-enabled casino experiences alongside wider gaming systems and integrations.
But whether the destination is a conventional online casino or a more custom gaming platform, I would keep one rule unchanged:
If the new system can show the player's balance but cannot explain how that balance got there, the wallet migration is not finished.
Top comments (0)