{ "openapi": "3.1.0", "info": { "title": "Sportsbook Customer Integration API", "version": "1.2.0", "description": "Create sportsbook sessions, manage ledger transfers and receive signed wallet and coupon callbacks. Monetary values are decimal strings." }, "servers": [ { "url": "https://admin.sportsbookapi.work" } ], "tags": [ { "name": "Customer API" } ], "paths": { "/api/integration/launch": { "post": { "summary": "Create an iframe session", "description": "Create a guest or member session. Launch links are valid for 60 seconds and can be used once. Read member identity from your server session. Use data.url as the iframe URL.", "tags": [ "Customer API" ], "security": [ { "SiteKey": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" }, "description": "UTC Unix timestamp in seconds. Clock difference must be less than 120 seconds." }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" }, "description": "A unique 16–128 character nonce for each HTTP attempt. Use letters, digits, underscores or hyphens." }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Lowercase hexadecimal HMAC-SHA256 of timestamp + LF + nonce + LF + METHOD + LF + path/query + LF + SHA256(rawBody). Do not add a sha256= prefix." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Launch" } }, "required": [ "ok", "data" ] } } } }, "401": { "description": "Invalid signature or timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Site, origin or server IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request replay, idempotency conflict or incompatible wallet operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Request failed. Include request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LaunchRequest" } } } } } }, "/api/integration/wallet": { "post": { "summary": "Transfer funds to or from a ledger wallet", "description": "Available for ledger sites. The member must have completed an iframe launch. Reuse the same idempotency_key and operation when retrying a transfer; generate a fresh signing nonce.", "tags": [ "Customer API" ], "security": [ { "SiteKey": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" }, "description": "UTC Unix timestamp in seconds. Clock difference must be less than 120 seconds." }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" }, "description": "A unique 16–128 character nonce for each HTTP attempt. Use letters, digits, underscores or hyphens." }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Lowercase hexadecimal HMAC-SHA256 of timestamp + LF + nonce + LF + METHOD + LF + path/query + LF + SHA256(rawBody). Do not add a sha256= prefix." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/WalletTransfer" } }, "required": [ "ok", "data" ] } } } }, "401": { "description": "Invalid signature or timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Site, origin or server IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request replay, idempotency conflict or incompatible wallet operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Request failed. Include request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRequest" } } } } } }, "/api/integration/credit": { "get": { "summary": "Get site betting credit", "description": "Returns site credit, separate from player wallet balances. Sign the GET request with an empty body.", "tags": [ "Customer API" ], "security": [ { "SiteKey": [] } ], "parameters": [ { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\d{10}$" }, "description": "UTC Unix timestamp in seconds. Clock difference must be less than 120 seconds." }, { "name": "X-Nonce", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{16,128}$" }, "description": "A unique 16–128 character nonce for each HTTP attempt. Use letters, digits, underscores or hyphens." }, { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "description": "Lowercase hexadecimal HMAC-SHA256 of timestamp + LF + nonce + LF + METHOD + LF + path/query + LF + SHA256(rawBody). Do not add a sha256= prefix." } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Credit" } }, "required": [ "ok", "data" ] } } } }, "401": { "description": "Invalid signature or timestamp.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Site, origin or server IP is not authorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Request replay, idempotency conflict or incompatible wallet operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid request fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Request failed. Include request_id when contacting support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "walletCallback": { "post": { "summary": "Receive a wallet or coupon event", "description": "Delivered to your configured callback_url. Verify sha256= + HMAC-SHA256(secret, timestamp + \".\" + rawBody). Process wallet changes and idempotency records in one transaction. Acknowledge after commit. wallet.balance expects HTTP 200 with the current balance. The callback timeout is 10 seconds.", "parameters": [ { "name": "X-Site-Key", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Callback-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Callback-Timestamp", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "X-Coupon-Signature", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/BalanceCallback" }, { "$ref": "#/components/schemas/CouponEvent" } ] } } } }, "responses": { "200": { "description": "Current balance or committed event response. A reserve rejection returns ok:false, code:INSUFFICIENT_BALANCE and the matching idempotency_key.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/BalanceReply" }, { "$ref": "#/components/schemas/CallbackReply" } ] } } } }, "default": { "description": "Delivery was not acknowledged and may be retried.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "SiteKey": { "type": "apiKey", "in": "header", "name": "X-Site-Key" } }, "schemas": { "Money": { "type": "string", "pattern": "^-?\\d+(\\.\\d+)?$", "description": "Decimal string. At least two fractional digits are returned in coupon events; meaningful additional precision is preserved. Example: 10.50 TRX. Avoid binary floating-point arithmetic." }, "Currency": { "type": "string", "enum": [ "TRY", "USD", "GBP", "EUR", "TND", "KWD", "BRL", "CAD", "AUD", "INR", "BDT", "MXN", "IQD", "ETB", "IDR", "TRX" ] }, "Error": { "type": "object", "properties": { "ok": { "type": "boolean", "const": false }, "code": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" }, "details": {} }, "required": [ "ok", "code" ] }, "LaunchRequest": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 80, "description": "Required for a member launch. Read from the authenticated server session. Allowed: letters, digits, spaces and _.@-." }, "external_user_id": { "type": "string" }, "guest": { "type": "boolean", "default": false }, "currency": { "$ref": "#/components/schemas/Currency" }, "language": { "type": "string", "enum": [ "tr", "en", "ru", "ar", "ja", "fa", "zh", "de", "es", "pt", "fr", "it", "ka" ], "default": "tr" }, "origin": { "type": "string", "format": "uri", "description": "An authorized HTTPS customer origin, without a path." }, "callback_url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Public HTTPS callback URL on port 443. Required for a seamless member launch if no callback is configured. Supplying it updates the callback URL for the entire site." } }, "required": [ "origin" ], "allOf": [ { "if": { "properties": { "guest": { "const": true } }, "required": [ "guest" ] }, "then": {}, "else": { "required": [ "username" ] } } ] }, "Launch": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "launch_token": { "type": "string" }, "site_key": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "url", "launch_token", "site_key", "expires_at" ] }, "WalletRequest": { "type": "object", "properties": { "username": { "type": "string", "maxLength": 80 }, "currency": { "$ref": "#/components/schemas/Currency" }, "operation": { "type": "string", "enum": [ "credit", "debit" ] }, "amount": { "type": "string", "pattern": "^\\d{1,12}(\\.\\d{1,8})?$", "description": "Positive decimal amount within the currency precision." }, "idempotency_key": { "type": "string", "pattern": "^[A-Za-z0-9_.:-]{16,160}$" } }, "required": [ "username", "currency", "operation", "amount", "idempotency_key" ] }, "WalletTransfer": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "balance": { "$ref": "#/components/schemas/Money" }, "currency": { "$ref": "#/components/schemas/Currency" } }, "required": [ "transaction_id", "idempotency_key", "balance", "currency" ] }, "Credit": { "type": "object", "properties": { "site_key": { "type": "string" }, "credit": { "$ref": "#/components/schemas/Money" }, "currency": { "$ref": "#/components/schemas/Currency" } }, "required": [ "site_key", "credit", "currency" ] }, "BalanceCallback": { "type": "object", "properties": { "event": { "type": "string", "const": "wallet.balance" }, "event_id": { "type": "string" }, "idempotency_key": { "type": "string" }, "site_key": { "type": "string" }, "username": { "type": "string" }, "currency": { "$ref": "#/components/schemas/Currency" } }, "required": [ "event", "event_id", "idempotency_key", "site_key", "username", "currency" ] }, "BalanceReply": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "balance": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$" }, "currency": { "$ref": "#/components/schemas/Currency" } }, "required": [ "ok", "balance", "currency" ] }, "CallbackReply": { "type": "object", "properties": { "ok": { "type": "boolean" }, "idempotency_key": { "type": "string" }, "balance": { "$ref": "#/components/schemas/Money" }, "currency": { "$ref": "#/components/schemas/Currency" }, "code": { "type": "string", "description": "Return INSUFFICIENT_BALANCE only when a wallet.reserve operation is definitively rejected for insufficient funds." } }, "required": [ "ok", "idempotency_key" ] }, "Selection": { "type": "object", "properties": { "event_id": { "type": "string" }, "market_id": { "type": "string" }, "selection_id": { "type": "string" }, "sport_id": { "type": "string" }, "sport_name": { "type": "string" }, "sport_alias": { "type": "string" }, "country_id": { "type": "string" }, "country_name": { "type": "string" }, "league_id": { "type": "string" }, "league_name": { "type": "string" }, "home_team": { "type": "string" }, "away_team": { "type": "string" }, "market_name": { "type": "string" }, "market_type": { "type": "string" }, "selection_name": { "type": "string" }, "line": { "type": [ "number", "string", "null" ] }, "scope": { "type": "string" }, "is_live": { "type": "boolean" }, "start_at": { "type": [ "string", "null" ] }, "displayed_odds": { "type": "string" }, "effective_odds": { "type": "string" }, "placed_score": { "type": [ "string", "null" ] }, "current_score": { "type": [ "string", "null" ] }, "full_time_score": { "type": [ "string", "null" ] }, "current_game_time": { "type": [ "string", "null" ] }, "current_game_state": { "type": [ "string", "null" ] }, "score_updated_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CouponSnapshot": { "type": "object", "properties": { "client_reference": { "type": [ "string", "null" ], "description": "Customer-facing placement reference associated with the coupon." }, "bet_type": { "type": "string", "enum": [ "single", "combo", "system" ], "description": "single, combo or system." }, "status": { "$ref": "#/components/schemas/CouponStatus" }, "status_label": { "type": "string", "description": "English display label. Use status for decisions." }, "revision": { "type": "integer", "description": "Settlement/cashout revision number; use it to order result updates." }, "total_stake": { "$ref": "#/components/schemas/Money" }, "total_odds": { "type": "string" }, "possible_win": { "$ref": "#/components/schemas/Money", "description": "Potential payout at placement, not confirmed winnings." }, "payout": { "$ref": "#/components/schemas/Money", "description": "Cumulative payout for the coupon, including cashout amounts. Do not credit this value again; apply the envelope amount." }, "remaining_ratio": { "type": "string", "description": "Fraction of the original stake still active. Full cashout leaves zero." }, "odds_format": { "type": "string" }, "odds_format_code": { "type": "integer" }, "odds_format_label": { "type": "string" }, "displayed_total_odds": { "type": "string" }, "selection_count": { "type": "integer" }, "cashout_count": { "type": "integer" }, "selections": { "type": "array", "items": { "$ref": "#/components/schemas/Selection" } }, "lines": { "type": "array", "items": { "type": "object", "properties": { "selection_ids": { "type": "array", "items": { "type": "string" } }, "stake": { "$ref": "#/components/schemas/Money" }, "odds": { "type": "string" }, "possible_win": { "$ref": "#/components/schemas/Money" } } } }, "cashout_summary": { "type": "object", "properties": { "total_amount": { "$ref": "#/components/schemas/Money" }, "remaining_stake": { "$ref": "#/components/schemas/Money" }, "remaining_possible_win": { "$ref": "#/components/schemas/Money" }, "history": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "mode": { "type": "string", "enum": [ "full", "partial" ] }, "amount": { "$ref": "#/components/schemas/Money" }, "used_stake": { "$ref": "#/components/schemas/Money" }, "remaining_stake": { "$ref": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time" } } } } } }, "settlement": { "type": [ "object", "null" ], "description": "Settlement source, revision and selection results. Result 1 loses; 3 wins at the selection odds; 2 and 4 use multiplier 1 (stake returned)." }, "settlement_locked": { "type": "boolean" }, "wallet_state": { "type": "string", "description": "Wallet processing state at snapshot time. Coupon status and wallet delivery are separate." }, "error_code": { "type": [ "string", "null" ], "description": "Machine-readable placement failure code, or null." }, "error_message": { "type": [ "string", "null" ], "description": "Human-readable failure text. Use error_code for handling." }, "error_details": { "description": "Odds-change details when error_code is ODDS_CHANGED; otherwise null." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "settled_at": { "type": [ "string", "null" ], "description": "Settlement timestamp or null while open." } } }, "CouponEvent": { "type": "object", "properties": { "schema_version": { "type": "integer", "const": 2 }, "event_id": { "type": "string" }, "event": { "type": "string", "pattern": "^(wallet\\.(reserve|refund|settlement\\.\\d+|cashout\\.\\d+)|coupon\\.(accepted|settled\\.\\d+|cashout\\.\\d+)|placement\\.unknown)$", "description": "Event kind and revision, not the bet result. In coupon.settled.1, coupon identifies a bet notification, settled means a settlement update, and 1 is the shared settlement/cashout revision. Determine won, lost, refunded, cashout or open from raw_payload.status. A later correction can arrive as coupon.settled.2. Only wallet events apply a balance delta; coupon notifications have amount 0.00.", "examples": [ "coupon.accepted", "coupon.settled.1", "coupon.settled.2", "wallet.settlement.1", "coupon.cashout.1", "placement.unknown" ] }, "site_key": { "type": "string" }, "idempotency_key": { "type": "string" }, "sequence": { "type": "integer", "description": "Delivery ordering value within the same bet_id. It is not a global event counter." }, "occurred_at": { "type": "string", "format": "date-time" }, "username": { "type": "string" }, "currency": { "$ref": "#/components/schemas/Currency" }, "amount": { "$ref": "#/components/schemas/Money", "description": "Signed wallet change for this event. Positive credits, negative debits, zero has no balance effect." }, "bet_id": { "type": "string" }, "raw_payload": { "$ref": "#/components/schemas/CouponSnapshot" } }, "required": [ "schema_version", "event_id", "event", "site_key", "idempotency_key", "sequence", "occurred_at", "username", "currency", "amount", "bet_id", "raw_payload" ], "description": "An event envelope with one coupon snapshot in raw_payload. amount is the wallet delta for this event; it is not the coupon stake." }, "CouponStatus": { "type": "string", "enum": [ "awaiting_wallet", "queued", "preparing", "processing", "open", "won", "lost", "refunded", "cashout", "failed", "unknown" ], "description": "Use the status code for application logic. Awaiting, queued, preparing and processing describe placement progress; not every transition produces a callback.", "x-enumDescriptions": { "awaiting_wallet": "Waiting for the customer wallet to acknowledge the stake reservation.", "queued": "Waiting to be processed after the reservation step.", "preparing": "Validating selections, odds and limits.", "processing": "The placement request is being processed.", "open": "Accepted; the remaining stake is awaiting settlement. Partial cashout also keeps this status.", "won": "Settled with at least one winning payable line. This does not necessarily mean a net profit on a system bet.", "lost": "The remaining bet is settled as lost. payout can include an earlier partial cashout.", "refunded": "The remaining bet is voided/refunded. Apply the wallet delta sent with the event.", "cashout": "The full remaining bet has been cashed out.", "failed": "The placement failed. A reserved stake is returned through wallet.refund when applicable.", "unknown": "Placement outcome needs confirmation. Do not automatically refund or place the bet again." } } } } }