# openlivegame Merchant Integration

> Bidirectional HTTP integration between a merchant and **openlivegame**, an iGaming
> Seamless Wallet platform. The merchant calls the Provider API to launch games;
> openlivegame calls the merchant's wallet endpoints to settle every bet, result, and
> refund in real time. openlivegame holds no funds - the merchant wallet is the single
> source of truth. Environment: Dev.

Base URLs (Dev):
- Provider API (merchant -> openlivegame): `https://api.open-live.win/provider/v1`
- Player game entry (gameURL landing): `https://client.open-live.win`
- Wallet callbacks (openlivegame -> merchant): a merchant-provided `callback_url`

Integration essentials:
- **Two surfaces.** Provider API (merchant -> openlivegame): `gameurl`, `getcasinogames`, `roundreport`, `healthcheck`. Seamless Wallet (openlivegame -> merchant; the merchant implements these): `authenticate`, `balance`, `bet`, `result`, `refund`.
- **Transport.** HTTP POST with `application/x-www-form-urlencoded` (`healthcheck` is GET); responses are JSON.
- **Signature.** Field `hash` = lowercase MD5 of the alphabetically sorted non-`hash` parameters joined as `k=v&...`, with `secretKey` appended. Identical in both directions.
- **Error type.** A string on the Provider API (`"0"` = success); an integer on Seamless Wallet (`0` = success). Business errors still return HTTP 200.
- **Idempotency (mandatory).** `bet` / `result` / `refund` are keyed by `reference` = `B|R|F` + 16-digit `roundId`; enforce a unique index on `(operator_id, reference)`.
- **Timeouts.** The `bet` callback is 5 s, others 10 s. A `bet` timeout or `error=100` causes openlivegame to queue a compensating `refund`.
- **Identity.** One `externalPlayerId` is bound to one `currency` for life; multi-currency users require distinct IDs (e.g. `uid_USD`, `uid_EUR`).
- **Money.** Decimal strings, 2 decimal places - use exact decimal types, never float.
- **Round keys.** The wallet field is `tableCode` (not `tableId`); a callback `gameId` may repeat across tables, so a round is uniquely identified by `(tableCode, gameId)` or by `roundId`.

## Documentation

- [Integration reference (Markdown)](https://doc.open-live.win/api.md): the complete machine-readable specification - every endpoint with field tables, the signing algorithm with a verified example, error-code tables, idempotency pseudocode, ordering rules, and a go-live checklist. Start here.
- [Integration guide (HTML / Chinese / English)](https://doc.open-live.win): the same material as a styled, bilingual reference with light/dark themes, search, and a sequence diagram. Best for human readers.

## Quick reference

- [Signing](https://doc.open-live.win/api.md#signing) - algorithm, reference implementations, and a self-check vector: inputs `secureLogin=merchant001 token=player-token-123 externalPlayerId=player-001 currency=USD gameId=545` with `secretKey=mysecretkey` produce MD5 `ce14a7aa5f8c5c23d92d088e94f76f19`.
- [Error codes](https://doc.open-live.win/api.md#error-codes) - Provider API (string) and Seamless Wallet (integer) tables.
- [Idempotency & ordering](https://doc.open-live.win/api.md#idempotency--ordering-mandatory-reading) - the three duplicate-request scenarios, a transactional `bet` implementation, and anti-patterns to avoid.