This lottery API integration guide is a buyer and implementation brief. It explains what to specify before choosing a delivery route and what evidence to request before acceptance. It is not WhiteLotto API documentation: the examples describe requirements to discuss, not confirmed endpoints, authentication methods, integrations or included features. Start with the WhiteLotto solution overview, then agree the actual interface scope with the delivery team.
Start with the integration boundary, not the endpoint list
Identify which system owns the player account, wallet ledger, ticket record, draw information, verification decision and customer communication. A separate front end, an existing operator back office and a third-party payment service create different boundaries. An API can expose a function without transferring operational responsibility for it.
Draw one transaction journey and mark every hand-off. For each boundary, record the calling system, authoritative record, permitted action, expected response and owner of an unresolved state. Include back-office access and reporting; an integration that serves the purchase journey but leaves finance unable to reconcile is incomplete.
Put this boundary map into the platform provider evaluation brief. Classify each requested capability as available and evidenced, configurable, custom, dependent on a third party, or outside scope. Do not treat a roadmap item as a committed interface.
API, iFrame or complete front end: choose the responsibility boundary
An API integration, an embedded iFrame and a supplier-delivered front end place different parts of the player journey under your control. Choose the route by the experience you need to own, the systems already in place and the team available to maintain the connection. This decision is separate from the commercial label “white label” or “turnkey”: agree the actual scope of both the interface and its operation.
Use the platform modules overview to identify what stays in your existing stack. Compare each delivery route against the same purchase journey rather than judging a self-contained demonstration.
| Delivery route | Player interface | Ownership to agree | Acceptance focus |
|---|---|---|---|
| API with your own front end | Your team builds the lottery journey around the agreed interfaces. | UI releases, adapter maintenance, account mapping and operational support. | Interface behaviour and the customer journey must work together. |
| Embedded iFrame | A supplied lottery interface sits within your existing site. | Session hand-off, surrounding navigation, communication between interfaces and incident routing. | Entry, purchase, recovery and return to the host site. |
| Complete supplied front end | The agreed website journey is delivered with the platform scope. | Branding, content changes, accounts, wallet boundaries, releases and exports. | The whole agreed journey, including administration and reporting. |
Resolve account, wallet and session boundaries before design approval
For an existing casino or sportsbook, specify whether a lottery player uses the existing account, a linked account or a separate registration. Name the system that enforces restrictions and decide what happens when verification or account permissions change during an active session. Ask how a player returns after logging out, switching device or following an expired link. An attractive embedded screen does not answer these operational questions.
Separate the displayed balance from the authoritative financial record. Agree which system authorises a purchase and how the host interface learns that funds, ticket status or permissions have changed. The wallet and reconciliation guide covers the financial boundary; the delivery model must explain how the player sees that boundary.
Assign each visible error to an owner. Distinguish a host-session problem, an unavailable embedded interface, a rejected lottery action and an unresolved transaction. Specify the message, permitted next action and support reference for each. Reopening the page should take the player to an agreed state, with an investigation route when the outcome remains uncertain.
Accept the integration model as well as individual transactions
Add model-specific checks to the UAT and go-live acceptance checklist. Test entry from the host site, session expiry during number selection, a changed account restriction, an unavailable component and a return from payment. Include mobile navigation, keyboard access and the player’s route back to their ticket history.
For every scenario, record the owning system, expected screen, authoritative account or transaction state and person responsible for resolution. Include the support hand-off between teams. A delivery route is ready when these responsibilities are accepted together, not merely when the embedded screen loads or an interface responds.
CONTACT to discuss your existing front end, account and wallet systems, and the lottery journey you want to add.
Build a requirements register that suppliers can answer
Use a row per interface or business operation, rather than one row called “API integration”. Add an owner, priority, dependency, evidence reference and acceptance decision to the following questions.
| Area | Requirement to define | Evidence to request |
|---|---|---|
| Interface contract | Operations, fields, identifiers, errors, version and supported environment. | Versioned specification and representative synthetic request/response examples. |
| Access boundary | Permitted clients, roles, brands and resources; issue, rotate and revoke access. | Access matrix and denied-action tests for the agreed deployment. |
| Money and tickets | Authoritative records, state transitions, draw cut-off and duplicate treatment. | Transaction trace connecting ticket, wallet and supplier references. |
| Asynchronous events | Authentication, duplicate handling, ordering, retries and recovery after a gap. | Documented event contract and failure-case results. |
| Capacity and limits | Expected peaks, concurrency, timeouts, rate limits and overload response. | Agreed workload assumptions and scoped test evidence. |
| Data and reporting | Required fields, retention, export permissions, timestamps and reconciliation views. | Data dictionary and usable sample export, without personal records. |
| Change and support | Compatibility, deprecation notice, incident ownership and exit arrangements. | Release process, escalation path and contractual scope. |
The OpenAPI Specification provides a standard way to describe HTTP interfaces. Ask whether the proposed interface has an up-to-date description, which version it uses, and which behaviour requires separate documentation. A machine-readable contract helps review; it does not prove transaction correctness, security or operational support.
Agree the data model and the system of record
Map identifiers across the operator, platform and external service. Distinguish a request identifier from a ticket identifier, a payment reference and a ledger entry. Decide how support can link them without putting personal information into URLs or unrestricted logs.
Specify amounts, currencies, precision, time zones, timestamp meaning and status definitions. “Accepted” might mean received for processing rather than a confirmed ticket. “Paid” might describe a processor event rather than final settlement. Document who can change each state and how corrections are recorded.
For draw and results data, define the authoritative source, freshness, correction policy and who settles affected tickets. Specify the sales cut-off time zone and the rule for a request arriving near the boundary; a front-end countdown is not the authority for ticket acceptance.
For player information, request only what each integration needs. Define access, retention, export and permitted use with the appropriate owners. The player data ownership guide separates useful operational access from broader contractual and privacy questions. Technical connectivity does not establish the right to transfer or reuse records.
Design for uncertain outcomes and repeated messages
Consider a synthetic purchase where the receiving service accepts the request but the connection closes before confirmation reaches the caller. A timeout is not proof that nothing happened. The specification needs a supported way to establish the original outcome and prevent a retry from creating a second financial effect.
HTTP semantics in RFC 9110 distinguish idempotent operations and caution against automatically retrying a non-idempotent request without knowledge that it is safe. For purchases and wallet changes, agree the application-level duplicate policy, the lifetime of its protection and what happens when the same reference arrives with different contents. Do not infer these guarantees from an HTTP method alone.
For events or callbacks, ask how the receiver verifies origin, detects duplicates, handles late or out-of-order delivery, and recovers missed processing. As a provider-specific reference, Stripe’s webhook documentation discusses signatures, repeated events and asynchronous handling. It is an example of the questions a contract should answer, not evidence that WhiteLotto uses Stripe or supports the same event model.
Acceptance should connect the final business outcome to its records: one intended purchase, the agreed wallet effect, a traceable ticket status and an owned exception if confirmation remains unresolved. Apply the same discipline to refunds, reversals and settlement. The lottery payment stack guide explains why a successful payment response and usable reconciliation are separate requirements.
Make security and capacity part of acceptance
Confirm the actual authentication mechanism, access scopes, credential owner, storage, rotation and revocation process. Never place production credentials in a procurement brief, shared example or browser-delivered code. Separate environments and use synthetic data for demonstrations.
Authorisation must be checked for the operation and the requested resource, not only for the existence of a valid login. Request tests for an unauthorised role, another brand or account boundary, and a revoked client. The OWASP API Security Top 10 is a useful reference for object-level access, authentication, resource consumption and inventory risks. It is not a certification or evidence that a particular platform passes those controls.
Describe the expected workload: steady traffic, a draw-related peak, concurrent purchases, reporting jobs and delayed-event recovery. Agree what happens when limits are reached and which requests can be deferred safely. Record latency and availability measurement boundaries, including dependencies, rather than inserting an unsupported performance target. Use the security, uptime and SLA checklist for the wider evidence and escalation discussion.
Use a small, complete acceptance pack
Record the interface version, configuration, test environment, synthetic fixtures, expected result and actual evidence for each test. Include the caller, receiver and operational owner. A screen recording alone does not establish the resulting ledger or ticket state.
- Trace one successful journey from request through confirmed outcome and reporting.
- Exercise a declined or invalid request, a draw cut-off boundary and an unresolved response.
- Repeat a permitted test request and event to verify the agreed duplicate policy.
- Test denied access, expired or revoked access, malformed inputs and agreed limits.
- Interrupt an external dependency and demonstrate recovery or an owned exception queue.
- Verify that support and finance can investigate using permitted records.
Keep blocking defects separate from optional improvements. The lottery platform demo checklist can help structure an evidence-led discussion, but a demonstration is not a substitute for acceptance of the contracted integration.
Test unresolved API operations, not only successful responses
Ask for an isolated demonstration using synthetic records: submit a ticket request, interrupt its confirmation, then retry with the same operation key. The acceptance evidence should connect the request, ticket status and financial record without making a real payment.
- Specify which system owns the final outcome and how a caller retrieves it when the first response is unavailable.
- Define pending, accepted, rejected and cancelled states; a timeout must not automatically mean that the purchase failed.
- Replay the request and event notification to check that neither tickets nor financial postings are duplicated.
- List unresolved operations in a reconciliation export, with references, timestamps and an assigned resolution owner.
Include recovery time and escalation ownership in the service requirements. Carry the same scenarios into the RFP acceptance matrix, rather than treating an API endpoint list as proof that integration recovery works.
Choose the architecture first, then prioritise each integration
Keep this guide as the parent requirements map. Do not start with every available provider at once: choose the systems of record and the smallest complete journey required for the agreed release. Record each interface’s business dependency, data owner, adapter owner, third-party access requirement and acceptance evidence.
| Workstream | Decision before building | Detailed guide |
|---|---|---|
| Draws and results | Authoritative draw identity, cut-off, result revisions and settlement ownership. | Draw and results integration |
| Payments | Wallet-credit rule, safe retry, verified events and finance reconciliation. | Payment gateway integration |
| KYC | Decision-state mapping, account permissions, manual handling and required data. | KYC integration requirements |
| Retail | Valid ticket acceptance, offline policy, device recovery and outlet settlement. | Retail POS integration |
| Player accounts (PAM) | Identity ownership, account states, restrictions, session access and event recovery. | Player account management integration |
| Subscriptions and multi-draw | Renewal versus prepaid purchase, payment retries, cut-off rules and ticket allocation. | Subscriptions and multi-draw requirements |
| Instant-win and digital scratch cards | Round commitment, outcome ownership, ledger postings and interrupted-play recovery. | Instant-win integration checklist |
| Jackpot risk and prize funding | Prize obligations, funding source, exposure limits and settlement evidence. | Prize funding and risk due diligence |
Order dependencies around a recoverable transaction
For a purchase journey, agree the account/control boundary, funding or wallet rules, accepted-ticket record, draw/result handling and financial export together. Build and test one end-to-end synthetic journey before multiplying providers. A disconnected set of successful API calls can still leave support unable to resolve an uncertain purchase.
Separate “must be ready for release” from “later commercial extension”. Integration scope includes monitoring, sandbox access, event recovery, documentation and partner coordination, not just the adapter code. A provider that has not approved the operating model or supplied a usable test environment remains a dependency, even when internal development is finished.
Make change ownership part of the contract
Keep a versioned interface inventory with the responsible owner and deprecation policy. Agree how changes to fields, signatures, status meanings and reporting are announced and accepted. Preserve the previous release path where it is safe, but recognise that rolling back an adapter does not reverse financial records already written.
The OpenAPI Specification is a reference for describing HTTP contracts. Business state transitions, recovery procedures and responsibility boundaries still need explicit documentation alongside it. Convert the agreed requirements into the UAT acceptance matrix and use the KPI framework to confirm the released integration remains observable.
Budget for ownership after the first release
Name the owner of each adapter, monitoring rule and incident route. Agree compatibility checks, notice for interface changes, a safe upgrade process and who pays for changes outside the original scope. Include partner coordination, reporting, test access and future migration work, not just coding the first connection.
Take the integration register into a WhiteLotto integration scoping conversation. Bring your system boundary diagram, required operations, traffic assumptions, target sequence and unresolved dependencies. Ask which requirements can be evidenced now and which need further discovery. Do not send player exports, credentials or private production logs.
Lottery API integration FAQ
Does this guide document the WhiteLotto API?
No. It is a requirements and acceptance guide. Obtain the current agreed specification and implementation scope directly from the delivery team before building against an interface.
Does an API remove the need for reconciliation?
No. Interfaces move information; reconciliation establishes whether related records agree and who owns a mismatch. Define it for wallet, ticket, payment and settlement records.
Can integration work be estimated from a list of providers?
A provider list is a starting point. A reliable estimate also needs operations, contracts, environment access, data mapping, failure behaviour, workload and acceptance responsibilities.
Can we keep our existing wallet, payment, KYC and CRM systems?
Retention of an existing system must be assessed against the agreed scope and its current, documented interfaces; it is not guaranteed by the label “API integration”. Identify the system of record for accounts, balances, verification decisions and customer messages, then map identifiers and business states across each boundary. Agree permitted actions, exception handling, acceptance evidence and an accountable owner for every connection. Include these requirements in the RFP evaluation checklist before deciding which components stay, which need adapters and which require a different operating boundary.
How should retries and duplicate callbacks be handled?
Define the required retry behaviour in the interface contract: use a stable business reference and an explicit idempotency boundary, with an agreed protection period. Incoming callbacks need origin verification and durable duplicate detection, so a replay cannot create another ticket or financial posting. When a response is uncertain, require status lookup or reconciliation before repeating an operation blindly. Acceptance tests should cover duplicate and out-of-order callbacks, interrupted responses and repeated requests with changed contents. The payment gateway integration guide provides a focused requirements checklist; these are acceptance requirements, not documentation of WhiteLotto endpoints.
Wojciech Lysak is the Managing Director of WhiteLotto.com. LinkedIn