Casino Wallet Settlement Architecture

Start with the actual wallet contract

An integration called a seamless wallet can describe very different protocols. Aggregator starts a game session with the balance supplied by your backend and delivers signed settlement events afterwards. It is not a generic per-bet balance-query or debit endpoint, and the command API does not debit your operator wallet for you.

Your backend owns reservations and the player ledger. Aggregator checks the command and enabled access, then returns the launch result. Player navigation to the home or cashier URL is not evidence that financial settlement has completed.

Persist a launch record before sending funds into a session

Store the player, play currency, exact catalogue identifier, starting amount, exact request and one idempotency key as an operation in your own system. Reserve the starting funds durably before dispatch. Keep this operation associated with the returned session and request IDs when available.

Prevent competing launches from reserving the same available funds. Your transaction boundaries and concurrency controls must preserve that invariant even if two requests arrive together. A lost HTTP response must not discard the durable operation record.

A successful response needs both HTTP success and numeric error: 0. For a timeout or unknown outcome, retain the reservation and reconcile the original operation; generating a new key creates a different operation, not a recovery query. Follow the launch contract and documented replay limitations.

Separate callback acceptance from financial application

1. Capture the raw request bytes. Verify x-callback-signature using HMAC-SHA256 and the callback secret before interpreting the body. Do not parse and reserialize JSON before verification.
2. Parse verified amounts without losing decimal precision. JSON number tokens can exceed the precision of ordinary JavaScript numbers; use a lossless parser and decimal storage for the documented amount range.
3. Claim the body serial_number durably within the workspace. A database uniqueness constraint or equivalent transactional guarantee must prevent concurrent workers from applying the same event twice. A process-local cache is not enough.
4. Resolve player, currency and session from trusted launch records. The callback may omit currency or session context. If association or ordering is ambiguous, retain the verified event for reconciliation and alert your operations team rather than guessing a wallet destination.
5. Commit the event and bookkeeping change atomically, or durably enqueue the event for processing, before acknowledging HTTP 2xx. If using an inbox, monitor pending, failed and unreconciled events: acceptance is not proof that the wallet has been updated.

Use the existing Node.js signature example with your framework's raw-body handling. The HMAC covers only the body; delivery headers are not authenticated ordering evidence. An already accepted duplicate can receive 2xx without another wallet update. The same serial with conflicting content needs an integrity investigation, not silent replacement.

Worked example: a snapshot is not an extra credit

Suppose a USD session starts with 1,000 and a verified round reports a bet of 10, winnings of 5 and credit_amount: 995. The 995 is the authoritative post-round balance for the associated play context. It is not an instruction to add another 995 every time the callback is delivered.

If an older snapshot of 1,000 arrives later, arrival order does not make it the newest balance. Reconcile event ordering before applying it. Do not overwrite an operator-wide wallet total when it also contains unreserved funds or other active sessions; your ledger must preserve those separate allocations.

Never reconstruct the authoritative balance from bet minus win. Those amounts also support reporting, but GGR funding is not the player wallet. Use the GGR calculator only for illustrative commercial fees, not settlement amounts.

Acceptance scenarios for your test environment

Invalid signature

Reject without financial processing. Log a non-secret diagnostic and correct the receiver; never bypass verification to clear a queue.

Two identical deliveries at once

Exactly one durable event/application survives. The other is an acknowledged duplicate, including after a worker restart.

Receiver commits, then the acknowledgement is lost

The durable serial prevents a second financial application if delivery is attempted again.

Receiver cannot persist the event

Do not acknowledge acceptance. Recover storage and inspect delivery eligibility rather than assuming unlimited redelivery.

Valid but unassociated or out-of-order event

Keep the evidence and raise a reconciliation task. Do not invent a currency or let an older snapshot overwrite a newer one.

Launch result remains unknown

Keep the original operation and reservation. Reconcile with request logs and support before releasing funds or sending another launch.

Delivery is bounded to three total attempts. Manual retries are subject to state, permission and recent MFA checks; unknown, in-flight, delivered and exhausted events cannot be blindly retried. See delivery recovery. Run these tests with synthetic data in your controlled environment, not by injecting fabricated financial events into a live account.

Make reconciliation an owned operational process

Retain non-secret request references, callback serials, processing states and decisions so an authorised operator can reconstruct what happened. Protect raw payloads under your retention and access policy; never put API keys, signing secrets or temporary launch URLs into support messages.

Finish the production checklist and assign responsibility for pending inbox items, funding, retries and unknown outcomes. Return to the integration handbook for the reference sequence. This architecture guide is a design aid, not a drop-in wallet implementation.