Integrate WINTO games with your own users & wallet.

Architecture

Quick Start

1. Receive your Partner Code and Partner Signing Secret from WINTO.
2. Implement the partner wallet operations on your backend and give WINTO the HTTPS wallet base URL.
3. Create a player session with POST /sessions using HMAC authentication.
4. Use the returned bearer session token for state, history and bet requests.
5. Use a stable bet_id. Never create a second ID merely because an HTTP response was lost.

Supported Game IDs

Authentication

Partner-authenticated requests use HMAC-SHA256. Session/game requests use a provider-issued bearer token.

Required HMAC headers

Canonical string

CopyMETHOD
PATH
TIMESTAMP
NONCE
SHA256(BODY)

signature = hex(HMAC-SHA256(partner_signing_secret, canonical_string))

Partner Credentials

User / Player Session

This is the user-data handoff. The partner keeps the full user record in its own database and sends only the game identity/profile fields WINTO needs.

Request

Copy{
  "external_player_id": "USER-10001",
  "game_id": "olapartydiamond",
  "display_name": "Rahul",
  "avatar_url": "https://cdn.partner.example/users/10001.jpg"
}

Current Session

Returns the authenticated provider session/player context. Send Authorization: Bearer <SESSION_TOKEN>.

Game State

Returns the current public game/round state for the game scoped to the session. Use server-provided round and timing information rather than inventing authoritative round state client-side.

Game History

Returns recent public completed-round history for the game scoped to the session. limit is optional.

Place Bet

The server resolves partner/player identity from the bearer session. Do not send a client-authoritative user ID, balance, winner or payout.

Copy{
  "round_id": 12345,
  "bet_id": "partner-order-000001",
  "bets": [
    { "target": 1, "amount": 10 }
  ]
}

Amounts are integer coins. bet_id is a stable partner request identifier. Repeating the exact accepted logical request with the same ID is idempotent.

Partner Wallet API

The wallet API is hosted by the partner, not WINTO. wallet_base_url in WINTO's partner configuration points to this HTTPS service. It queries/updates the partner's own wallet tables.

Wallet — Balance

Returns the authoritative current wallet balance for an external player.

Copy{
  "external_player_id": "USER-10001"
}

Wallet — Debit

Deducts a bet amount exactly once. The transaction ID must be unique and idempotent.

Copy{
  "external_player_id": "USER-10001",
  "transaction_id": "bet-partner-order-000001",
  "amount": 100
}

Wallet — Credit

Credits a WINTO-determined payout exactly once using a stable transaction ID.

Copy{
  "external_player_id": "USER-10001",
  "transaction_id": "win-partner-order-000001",
  "amount": 150
}

Wallet — Refund

Reverses an eligible original debit. The partner must make duplicate refund requests idempotent.

Copy{
  "external_player_id": "USER-10001",
  "transaction_id": "refund-partner-order-000001",
  "original_transaction_id": "bet-partner-order-000001"
}

Wallet — Transaction Status

Authoritative lookup used to resolve ambiguous network outcomes. It must answer whether the stable transaction ID exists and its final state without creating a new financial operation.

Settlement Model

Native WINTO round workers are the authority for result generation. The client/partner must never submit the authoritative winner or payout.

HTTP & Error Behavior

Security Requirements

• HTTPS only; keep TLS certificate verification enabled.
• Keep all signing secrets server-side and outside source control.
• Synchronize backend clocks with NTP.
• Use a cryptographically random, one-time nonce for every HMAC request.
• Sign the exact HTTP method, path and raw body sent on the wire.
• Never log secrets, bearer tokens or complete Authorization headers.
• Never accept client-provided winner, payout, wallet balance or settlement status as authority.
• Use stable transaction IDs for financial idempotency and reconciliation.

Production Go-Live Checklist

• Partner code and signing secret exchanged securely.
• Partner HTTPS wallet base URL configured.
• Separate wallet authentication secret configured securely.
• Source IP allow-list agreed where required.
• HMAC valid, replay, expired timestamp and tamper tests passed.
• Session creation and bearer-token handling passed.
• State/history verified for every enabled game.
• Stable bet IDs and duplicate-request behavior tested.
• Balance/debit/credit/refund/transaction-status behavior tested.
• Win, loss, refund, timeout and reconciliation tested before production.