# CasinoGate Providers API — Integration Guide > **Read this first.** This guide explains, step by step, **what you call, in what order, and what comes back**. This is the **Providers API**, used by the **Casino Platform**. After you launch a game (via the Platform API) the player lands in the game; on every wallet interaction — read the balance, place a bet, settle a win, refund — you call us with the session **`token`** you sent at launch, and we answer with the **current wallet state**. - **Base host:** `https://api-stage.casinogate.pt` (staging). Production host is given to you during onboarding. - **Base path:** `/v1/providers/{platformId}` - **Auth:** HTTP **Basic Auth** when credentials are configured for your integration (you are told at onboarding). - **Spec files:** [`providers_swagger.json`](https://s3.casinogate.io/game-aggregation/providers_swagger.json) · [`platform_swagger.json`](https://s3.casinogate.io/game-aggregation/platform_swagger.json). Import either into Postman or Swagger UI. `{platformId}` is **your** identifier, assigned to you during onboarding. Put it in the URL. ## The single most important concept: the `token` ```mermaid flowchart LR You[Casino Platform
you] GA{{CasinoGate}} Session(["Game session
one player + one game"]) You -->|1 send your token at launch
PLATFORM API| GA GA -->|2 binds your token to| Session You ==>|3 echo the SAME token on every
wallet / bet / win / refund
PROVIDERS API| GA GA -.->|resolves your token to| Session classDef us fill:#2d6cdf,color:#fff,stroke:#1b3e80; classDef sess fill:#eaf7ea,stroke:#2e7d32,color:#14532d; class GA us; class Session sess; ``` > **Key concept:** one `token` = one player + one game = one session. Never invent it; always echo the exact one you > sent at launch. ## The wallet lifecycle of one game round This is the heartbeat of the integration. Typical round: read the wallet → place a bet (debit) → settle with a win (credit). A refund only happens when a bet must be rolled back. ```mermaid sequenceDiagram autonumber participant CP as Casino Platform (you) participant GA as CasinoGate Note over CP: Player opens the game CP->>GA: POST /wallet { token } GA-->>CP: 200 { balance, currency, denomination } Note over CP: Player spins (one round = one roundId) CP->>GA: POST /bet/place { token, roundId, transactionId, amount } GA-->>CP: 200 { balance } (bet deducted) alt Player wins CP->>GA: POST /bet/win { token, roundId, transactionId, amount } GA-->>CP: 200 { balance } (winnings credited) else Player loses Note over CP: No win call needed.
The bet already debited the balance. end opt Something went wrong with the bet CP->>GA: POST /bet/refund { token, roundId, transactionId, refundTransactionId, amount } GA-->>CP: 200 { balance } (bet returned) end ``` > **Note:** `roundId` ties a bet to its win/refund. Use the **same `roundId`** for every transaction in one game > round. Each money movement gets its **own unique `transactionId`**. ## Idempotency — the rule that prevents double-charging Networks retry. You **will** sometimes send the same request twice. The service is keyed on `transactionId`: if you resend a `transactionId` that was **already processed**, it is **not applied again** (no double debit/credit). But instead of a fresh wallet you get a **`400` with application code `7005`** (`transaction had already processed`). ```mermaid flowchart TD A[You send bet/place, bet/win or bet/refund] --> B{Have we seen this
transactionId before?} B -->|No, first time| C[Apply it: debit/credit the wallet] --> D[200 OK + new balance] B -->|Yes, duplicate| E[Do NOT apply again] --> F["400 Bad Request
{ code: 7005, description }"] style F fill:#fff3cd,stroke:#caa700 ``` > **Note:** treat code `7005` as 'already done', not a hard failure. It confirms the original movement stuck, so you > will **not** be charged twice. The `400` body is the standard error shape `{ code, description }`, **not** a wallet, so > it carries no balance. If you need the current balance after a duplicate, call **`POST /wallet`** to read it. > > **Always use a unique `transactionId` per real money movement** so a genuine retry resolves to `7005` instead of > creating a second charge. ## End-to-end: one player, both APIs ```mermaid sequenceDiagram autonumber participant Player as Player participant CP as Casino Platform
(you) participant GA as CasinoGate participant GP as Game Provider
(hosts the game) rect rgb(232,240,254) Note over CP,GA: PLATFORM API Player->>CP: Click Play CP->>GA: POST /game-launch { gameId, userId, currency, token T } GA-->>CP: 200 { url } CP-->>Player: redirect to url Player->>GP: game loads end rect rgb(234,247,234) Note over CP,GA: PROVIDERS API (token T echoed on every call) CP->>GA: POST /wallet { token T } GA-->>CP: 200 { balance } CP->>GA: POST /bet/place { token T, roundId R, txn B1, amount } GA-->>CP: 200 { balance- } CP->>GA: POST /bet/win { token T, roundId R, txn W1, amount } GA-->>CP: 200 { balance+ } end Note over Player,GP: Player keeps spinning — repeat place/win per roundId. ``` ## Authentication When enabled for your integration, attach **HTTP Basic Auth** to every request (username + password issued during onboarding). There is no login call and no bearer token. > **Warning:** `401` means wrong Basic Auth credentials only. A bad or expired session **`token`** is a different > failure: it returns **`404`** (the session is not found), not `401`. ## Money & values | Rule | What it means | |--------------------|-----------------------------------------------------------------------------------------------------------------| | **Integers only** | `amount`, `balance` are **whole numbers**, never decimals. | | **Minor units** | Values are in the currency's smallest unit. With `denomination = 100`, `balance = 100000` means **1000.00 EUR**. | | **`denomination`** | The divisor to convert to a human amount: `human = balance / denomination`. | | **`currency`** | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code, e.g. `EUR`, `USD`, `BRL`. | | **`buffer`** | An opaque JSON object. If you receive it, **store it and send it back unchanged**. Do not interpret it. | ## Error responses Failures return a small JSON object with a numeric **`code`** and a human **`description`** (the field is `description`, **not** `message`): ```json { "code": 7007, "description": "insufficient funds" } ``` This service uses a **narrow set of HTTP statuses**: it never returns `409` or `422`. Business-rule failures come back as **`400`** carrying an application `code`. | Status | Meaning | Typical cause | |:------:|-----------------------|---------------------------------------------------------------------------| | `400` | Bad Request | Missing/invalid field, malformed JSON, **or** any business-rule failure (`7xxx` code) | | `401` | Unauthorized | Wrong **Basic Auth** credentials (not the session `token`) | | `404` | Not Found | **Unknown/expired session `token`** (session not found) | | `500` | Internal Server Error | Our side failed; body is `{ "code": 0, "description": "something went wrong" }` | **Application `code` values (returned with `400`):** | `code` | Meaning | Where you'll see it | |:------:|---------------------------------------|---------------------------------------------| | `7001` | Session validation failed | Wallet / bet calls with a bad session | | `7003` | Currency mismatch | Bet does not match the session currency | | `7004` | Game round was not previously created | `bet/win` for a round that never had a bet | | `7005` | Transaction already processed | Duplicate `transactionId` (see idempotency) | | `7006` | Bet transaction not found | `bet/refund` for an unknown original bet | | `7007` | Insufficient funds | `bet/place` the player can't afford | | `7008` | Transaction already refunded | `bet/refund` sent twice | | `7019` | Game round already closed | `bet/place` and `bet/win` after round close | ## Glossary | Term | Meaning | |---------------------------|--------------------------------------------------------------------------------------------------| | **`platformId`** | Your Casino Platform identifier, issued at onboarding. Goes in the URL path. | | **`token`** | The session reference you sent at launch. Echo it **unchanged** on every call. | | **session** | One player + one game, identified by the `token`. | | **`roundId`** | Identifier of one game round; the **same** across place/win/refund of that round. | | **`transactionId`** | **Unique** id per money movement (one per place, per win, per refund). Drives idempotency. | | **`refundTransactionId`** | New unique id for a refund; on `bet/refund` the `transactionId` carries the **original bet's** id.| | **`endRound`** | On `bet/win`, whether the win closes the round. Optional, defaults to `true`. | | **`freeSpinId`** | On `bet/place`, consumes one free spin instead of the cash balance. | | **`currency`** | [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) code, e.g. `EUR`, `USD`, `BRL`. | | **`denomination`** | Divisor converting minor units to a human amount: `human = balance / denomination`. | | **`balance` / `amount`** | Money in the currency's smallest unit, as whole integers (never decimals). | | **`buffer`** | Opaque JSON object. Store it and send it back unchanged; do not interpret it. | ## Casino Platform quick checklist 1. On game open → `POST /wallet` with the `token` to read the balance. 2. Per spin → `POST /bet/place` (one `roundId`, unique `transactionId`). 3. On win → `POST /bet/win` (same `roundId`, new `transactionId`). 4. On rollback → `POST /bet/refund` (original bet `transactionId` + a new `refundTransactionId`). 5. Always use a unique `transactionId` per movement; a repeat returns `400` code `7005` — read `/wallet` if you need the resulting balance.