Online Casino Payment Gateway Integration: Technical Checklist

A gateway integration is ready when the operator can explain where a player's money went after an interrupted request, a repeated notification or a delayed payout. A successful API call is only one part of that proof. The practical deliverable is an agreed contract linking the payment service provider (PSP), the player wallet, the financial ledger and the people who resolve exceptions.

This checklist is for engineers, payments managers and finance teams preparing a casino integration. Start with the approved operating entity, merchant account, markets, currencies and payment methods. Confirm deposits and payouts separately: availability for one does not establish support for the other. Record the provider product and API version, capture model, reporting access and escalation contacts. Technical access alone does not establish approval to process gambling payments.

Use the provider documentation below as concrete examples of integration behavior, not as a recommendation or confirmation of eligibility. For each supported method, collect a normal deposit, a normal withdrawal and at least one recovery case with matching provider references and ledger entries. Define this scope alongside your payments and identity-verification integration, before building the connector.

Deposits: define the evidence that permits a credit

Create a durable deposit record before initiating the provider request. Give the player's logical request a stable ID and each external attempt its own identity. Persist the amount, currency, player, brand, merchant account and intended operation. The server must decide these values from an authorized request; a browser-supplied wallet ID or amount is not a trusted instruction to credit money.

Agree exactly which provider evidence permits wallet credit for the method and capture model. A return to the success page is not that evidence. Validate the authenticated server event or authoritative status response against the expected attempt, account, amount and currency. If partial authorization is supported, do not credit the full requested amount on the strength of a smaller authorized amount. Decide whether to accept a partial payment or cancel it, and reflect the actual accepted amount.

Write the accepted payment fact and the corresponding ledger posting atomically, or use a durable, replayable handoff when separate services prevent a single transaction. The handoff must detect an already committed posting after a crash. Two copies of the same qualifying event must produce one credit. A later capture failure, refund or chargeback is a new financial fact with its own treatment, not a reason to overwrite the earlier history.

For example, a player closes the payment page before returning to the casino. If valid confirmation arrives and the credit policy is satisfied, the deposit still needs processing. Conversely, an attractive success screen with no qualifying confirmation must not create spendable funds.

Withdrawals: reserve funds before sending

A withdrawal begins with an authorized request and a ledger reservation that removes the amount from the player's available balance. Commit the reservation before an external payout can be sent. Otherwise the player may spend the same funds while the provider is processing the transfer. The reservation and payout record must share a stable withdrawal identity.

Bind the approved destination, amount, currency and player to that record. A retry must not quietly change the beneficiary. Revalidate any required conditions at the stage defined by the operator's policy, and serialize the transition that authorizes sending so competing workers cannot initiate two transfers.

Keep the money unavailable while the external outcome is unknown. Consume the reservation on recorded payout completion, or release it only when confirmed evidence permits that action. A return after completion needs a new ledger entry; it must not release the already consumed reservation a second time. A local timeout, an operator pressing cancel or an estimated arrival time does not prove that funds were never sent. If a returned transfer includes deductions or currency conversion, account for the confirmed amounts rather than restoring the original amount by assumption.

Provider vocabulary needs careful mapping. In Adyen's payout-service transfer lifecycle, booked means funds have been deducted from a balance account and is not final: a transfer can subsequently fail or be returned. That example describes a specific product, not every casino payout arrangement. Obtain the equivalent evidence for your provider, including the trace reference that support can use when the recipient reports missing funds.

Separate API credentials, card authentication and player checks

There are three different questions: may this server call the provider, has the payment instrument undergone the required authentication, and may this player perform this transaction? An API key answers the first. Issuer authentication answers a different question. Neither replaces the operator's player-verification, account restrictions or withdrawal controls.

Implement the actual provider API authentication contract. Adyen, for example, documents API-key and Basic authentication alternatives. Keep server secrets out of browser code, logs and support exports. Separate test and live credentials and merchant accounts; restrict credential access and administrative changes to the people and services that need them. Rotation should include deployment, verification and removal of the previous credential, with a recovery plan for requests already in flight.

Choose payment-data handling deliberately. Hosted components or tokenization may reduce the data your systems handle, but outsourcing does not remove all responsibility. PCI SSC's outsourcing guidance says merchants remain responsible for third-party protection of account data and should confirm their validation obligations with the organization managing their compliance program. Establish your actual scope with the acquirer or payment brand; do not label an integration compliant simply because the provider is compliant.

The acceptance evidence is a permitted call from the intended service and account, rejection of unauthorized access, and a documented boundary for payment data and secrets. Avoid copying sensitive payloads into a debugging system merely to make testing easier.

Webhooks: verify, persist, acknowledge, then process

Verification must follow the webhook type's documented algorithm. Do not invent one universal signature check. Adyen's HMAC documentation distinguishes standard notifications signed over selected fields from other webhook types signed over the original request body. In the latter case, deserializing and reserializing the body before verification can change the signed bytes. Use the appropriate supported verifier and test with provider-generated fixtures.

For an authentic message, first persist a durable inbox record, then acknowledge receipt as the provider requires, and process the financial transition separately. Adyen's handling guidance describes this separation and warns that duplicate notifications can have differing event dates or details. A successful acknowledgement should mean the integration can recover the message after a restart; it need not mean the wallet has already been updated.

A valid signature is not enough to authorize a wallet posting. Match the merchant account and environment, provider reference, operation, amount and currency to a known payment. Reject or quarantine mismatched events before they can affect a player balance. Preserve enough protected evidence for investigation. An authentic event for an unknown reference needs an assigned investigation, not a guess about which player it belongs to.

Deduplicate according to the provider's event identity and semantics. Repeated authorization is different from a later capture, refund or return. Some repeated events carry updated details that matter even when they must not produce another posting. Handle event chronology using the available provider sequence, timestamps and transition rules; arrival order alone is insufficient. Keep verification-key rotation compatible with legitimate delayed notifications under the provider's documented rules.

Model financial facts separately from API progress

A single paid flag cannot explain transport progress, the provider's decision, the wallet posting and settlement. Keep these dimensions separate and retain the original provider status beside its local interpretation. The following labels describe an internal design; they are not universal PSP status codes.

• Prepared or submitted: an external attempt exists, with recorded send progress. Prepared does not prove that a send never occurred if the process crashed at the network boundary.
• Action required or pending: additional authentication or asynchronous processing is outstanding. Show an honest pending state without issuing another payment automatically.
• Outcome unknown: the request may have reached the provider, but the integration lacks decisive evidence. Assign recovery rather than treating this as a decline.
• Provider confirmation and ledger result: retain both facts. A qualifying payment with no corresponding credit is a repair case; a local posting does not prove settlement.
• Later adjustment: capture, refund, payout return and chargeback have their own identities, amounts and effects. Preserve the sequence instead of flattening it into the latest label.

Adyen's payment result codes illustrate why this distinction matters: Received and Pending are intermediate, and Authorised can still require capture when manual capture is used. Decide the wallet-credit point explicitly for the approved method. Authorization is not a promise of irreversible settlement.

Write transition tests for conflicting and delayed evidence. A stale pending event must not erase a confirmed capture. A later, genuine reversal must remain visible even if the customer interface continues to display the original deposit.

Idempotency needs protection at both ends

Protect three boundaries: the player's repeated request, the external provider call and the local financial posting. At the first, bind an idempotency identity to one authorized operation and an immutable payload. Reusing the identity with a different amount, currency or destination must fail, not return an unrelated success.

At the provider boundary, persist the key with the exact attempt before sending. Follow the provider's retry conditions, scope and retention period. Adyen's idempotency documentation specifies account-level scope and limits across regional endpoints, and defines a transient-error signal for retries. A key is a contractual deduplication mechanism with boundaries, not permanent global protection. When those boundaries no longer establish safety, investigate the original attempt rather than silently issuing a fresh key.

At the ledger boundary, enforce a unique posting identity for the relevant financial operation. Check-and-then-insert application code alone can race; the durable store must reject duplicates. Use separate identities for genuinely separate captures, refunds or returns. A blanket rule allowing only one event per payment would discard legitimate financial changes.

Test the crash between committing a posting and marking its inbox event processed. On replay, the posting already exists and must be recognized. If the wallet lives in another service, its receiving contract needs the same protection. The complete outcome should be recoverable processing with one intended financial effect, not a claim that networks deliver messages exactly once. The wallet and transaction-ledger design is part of the integration contract.

Recover a lost response without creating another payment

Consider a deposit attempt A. The provider accepts it, but the response is lost. The browser resubmits and a worker restarts before a webhook arrives. Neither event proves a decline. Keep the logical deposit linked to A and prevent a second attempt from being sent while A remains unresolved.

1. Recover the saved attempt, payload and provider idempotency key. Preserve the uncertainty if the process cannot prove whether the request crossed the network boundary.
2. Obtain authoritative status or use the provider's documented retry mechanism for the same attempt, when its conditions permit. Record every recovery action and response.
3. Let qualifying evidence enter the same validation and posting path as normal processing. A late webhook and a recovered API response must converge on one financial effect.
4. Escalate unresolved cases with their age, references and owner. A missing record in one query or one report is not sufficient proof of failure unless the provider contract makes that result decisive for this request.

Apply the same discipline to payouts, retaining their fund reservation. Changing provider or creating a fresh key while the first transfer might still complete can duplicate the external payment. The recovery design must say when a new attempt becomes permissible and what evidence closes the old one. Broader routing decisions belong in the payment orchestration and recovery architecture.

The diagram below is a simplified deposit path. In production, requests, notifications and recovery can arrive through separate channels. A withdrawal also reserves funds before sending; it cannot simply copy the illustrated ordering.

Prove the link from the wallet to settlement

Prove four connections: the accepted provider operation to the player's ledger entry; adjustments to their original operation; settled transactions to the provider's settlement batch; and the batch to the cash actually received. Payouts need their corresponding external transfer and cash records. Reconcile by entity, merchant account, currency and financial period, not by a single success counter.

Retain internal and provider references, operation type, exact amounts, currency, posting dates and batch identifiers. Use the provider's specified amount representation at the API boundary and an exact monetary representation internally. Validate the currency and the method's amount rules before sending; reject unsupported values rather than rounding them silently. Do not guess decimal scaling from a displayed amount. Time zones, settlement cutoffs and report availability determine whether a discrepancy is expected timing or an exception.

The Adyen Settlement details report is an example of transaction-level evidence containing gross and net currencies and amounts, references and fee fields. Its commission may appear as a total or as components. Map the actual report format so costs are not counted twice. Such a report describes its own settlement scope; it is not automatically a complete view of all business costs or externally settled cash.

Useful exception classes include confirmed deposits with missing credits, duplicate postings, unmatched refunds, unresolved payout reservations and settlement amounts that do not match cash after documented adjustments. Give each an owner, age, evidence and next action. Repair through authorized ledger entries or a replayable posting path, preserving the original evidence. Do not edit a player's balance manually to make a daily total look correct.

Apply risk controls without losing the financial history

Define the operator's rules for account eligibility, payment-instrument ownership, transaction limits, withdrawal approval and restricted accounts for the applicable markets. The integration must enforce the relevant decisions server-side at the agreed stages. This article does not prescribe one global KYC rule or legal retention period.

Keep decision evidence proportionate and protected: which policy version applied, what decision was made, when, and by which service or authorized reviewer. Limit access to payment settings, destination changes, refunds and manual corrections. Test authorization across brands and player accounts, not just whether an endpoint accepts a valid login. The platform security architecture should define these trust boundaries.

A risk block does not make an external payment disappear. If a deposit is confirmed after the account becomes restricted, record the financial fact and follow the operator's approved treatment, such as a controlled refund or restricted funds. Do not ignore the confirmation, expose blocked funds as spendable or pretend the original charge failed. Likewise, stopping a payout locally requires resolving the external transfer before releasing its reservation.

Give support a safe view of status, timing and references, with clear escalation ownership. Access to secrets or unrestricted balance changes is not a substitute for a usable investigation workflow.

Make the release decision with evidence

Run each acceptance case against the exact approved merchant configuration and payment method. The evidence packet should contain the request and attempt identities, sanitized provider evidence, final ledger entries, reservation changes and reconciliation result. Specify the expected outcome before the test; a green response code is not a pass criterion.

Sandbox tests establish functional behavior. They do not establish live approval, production credentials, actual settlement reporting or operational readiness. Where the provider and operator permit a controlled live validation, bound it by supported entities, methods and amounts, and include finance and support in the review. Confirm the live webhook endpoint, keys, report access and alert ownership before opening broader traffic.

Define how to stop new deposits or payouts without losing processing for existing attempts, late callbacks and returns. A rollback must preserve pending records and the jobs that reconcile them. Monitor unresolved outcome age, confirmed payments without postings, stuck reservations and failed inbox processing, with actionable thresholds chosen for each method.

The eight checks below form a minimum evidence set, not a guarantee of approval or completeness. Add method-specific authentication, partial payments, capture, refunds and dispute scenarios wherever the actual product supports them. Release only with agreed owners for the remaining exceptions and a documented decision about which unresolved conditions block new traffic.

• Repeated player request: concurrent submissions of the same operation create one external attempt; reusing its identity with a changed amount or beneficiary is rejected.
• Authenticity and ownership: a bad signature, wrong environment or wrong merchant account cannot credit a wallet; an authentic unknown reference enters an owned investigation.
• Duplicate and delayed events: repeated confirmation produces one posting, while a genuine later capture, refund or return remains processable.
• Lost response and restart: an accepted request with a dropped response recovers without another charge or payout, including a crash immediately after a ledger commit.
• Payout uncertainty: available funds are reserved before send and stay unavailable during an unresolved outcome; a confirmed return is accounted for with its actual amount.
• Financial reconciliation: provider operations match ledger entries, and settlement batches match cash with documented timing, fees, currencies and adjustments.
• Access restrictions: unauthorized destination changes, cross-player access and cross-brand operations fail without changing funds or sending a provider request.
• Live configuration and rollback: credentials, callbacks and reports use the intended account; stopping new traffic preserves recovery and reconciliation of existing operations.