Lottery Payment Gateway Integration: Webhooks, Retries & Refunds
A lottery payment gateway integration is ready when payments, wallet postings and settlement reports agree—even after retries, timeouts, refunds and delayed notifications. A successful checkout screen is not sufficient evidence that the operator received funds or credited the correct account once. This guide describes integration requirements, not actual WhiteLotto API fields or a promise of […]
A lottery payment gateway integration is ready when payments, wallet postings and settlement reports agree—even after retries, timeouts, refunds and delayed notifications. A successful checkout screen is not sufficient evidence that the operator received funds or credited the correct account once.
This guide describes integration requirements, not actual WhiteLotto API fields or a promise of support for a named processor. Provider eligibility, accepted products and commercial terms must be confirmed separately. Read the lottery payment stack guide for the wider operating and cost picture.
Separate the processor, wallet and finance records
Agree which system owns the payment attempt, final provider outcome, player wallet entry, withdrawal instruction and accounting reconciliation. Link their identifiers without treating them as interchangeable. Define amounts, currency, rounding and fees at each boundary.
| Situation | Required behaviour | Evidence to retain |
|---|---|---|
| Created or pending | Do not confuse an initiated operation with a completed funding event. | Operation ID, provider reference and current status. |
| Authorised or captured | Apply the agreed wallet-credit rule for the actual payment method. | Verified provider event and linked ledger posting. |
| Uncertain response | Determine the original outcome before creating a new operation. | Retry/query history and final resolution. |
| Refund or reversal | Link the adjustment to the original payment and avoid duplicate effects. | Adjustment reference, amount, reason and approval. |
| Dispute or settlement gap | Create an owned exception with a finance response. | Provider report, internal record and resolution trail. |
Design webhook handling for repetition and delay
Verify the event origin using the provider’s documented mechanism before trusting its contents. Validate the referenced account, payment, amount and currency. Persist the accepted event or operation before returning the response that tells the sender delivery succeeded. Process longer work through a recoverable path.
Do not assume events arrive once or in order. Stripe documents signature verification, duplicate events and non-guaranteed event ordering. Adyen documents its own webhook acknowledgement and duplicate-handling rules. They are provider-specific references, not evidence of a WhiteLotto integration with either company.
Choose deduplication keys and state-transition rules from the actual provider contract. A new delivery identifier can represent the same business event. A delayed event must not regress an already resolved operation. Keep failures visible in an exception queue and provide a controlled replay process.
Define safe retries and uncertain outcomes
Suppose the provider completes a funding operation but the response never reaches the platform. Starting a new payment can charge the player again. Reuse the supported operation reference or idempotency mechanism and retrieve the original outcome.
Stripe’s idempotency documentation illustrates how one provider defines replay behaviour. Do not copy its retention window or error semantics to another provider. Your contract needs the protection lifetime, payload-conflict behaviour and recovery path after that lifetime expires.
Test concurrency as well as repetition: two workers may receive the same event simultaneously. A retry control that works only in a single browser session is not enough to protect a shared wallet ledger.
Reconcile gross movements and differences
Match provider operations to wallet postings and provider settlement reports. Explain fees, partial refunds, disputed amounts, exchange differences and timing gaps separately. Deposits are not ticket sales; successful funding does not prove that a later ticket purchase was accepted.
Finance should be able to investigate an unmatched amount using permitted references, timestamps and status history. Use the KPI framework to report unresolved value and ageing without hiding opposite-sign differences through netting.
Payment acceptance checklist
- Exercise successful, declined, cancelled and pending funding journeys.
- Lose the first response, then retrieve or safely retry the original operation.
- Send duplicate, concurrent, delayed and out-of-order test events.
- Reject invalid signatures, wrong currencies and unrelated account references.
- Test full and partial refunds, withdrawal failure and reconciliation gaps.
- Confirm secrets are not present in browser code or unrestricted logs.
Run these cases in authorised provider sandboxes with synthetic data. The OWASP payment testing guidance is a useful reference for business-logic and timing checks. Record actual financial outcomes in the UAT acceptance pack; this checklist does not authorise live payments.
Payment integration FAQ
Should a browser redirect credit the wallet?
The credit decision needs authoritative server-side evidence under the agreed contract. A browser success page alone is not that evidence.
Does a gateway integration guarantee acceptance of a lottery business?
No. Eligibility, market/product approval and commercial onboarding are separate decisions made by the provider and relevant owners.
Bring your payment methods, markets and settlement requirements to WhiteLotto. Start with the integration architecture. CONTACT.