# Merchant Integration Guide

> Integration guide for merchants of the live-game platform. Two directions, one signing scheme: the Platform API is called by the merchant (game catalog, game launch, round report URL); the Wallet API is a seamless wallet implemented by the merchant under its callbackUrl and called by the platform (auth, balance, debit, credit, rollback). All requests are JSON over HTTPS, signed with HMAC-SHA256 over METHOD, path, X-Merchant-Code, X-Timestamp, X-Request-Id and the SHA-256 of the raw body. Business results are always HTTP 200 with a result code in the envelope {code, message, data}.

Version: API v1 · 2026-11-02. Full text in one file: [llms-full.txt](llms-full.txt)

Key rules for generating integration code:
- Sign and send the exact same body bytes; verify signatures on the raw body before parsing JSON; compare in constant time.
- Reject |now - X-Timestamp| > 300 s with TIMESTAMP_EXPIRED; use a new X-Request-Id for every request, retries included.
- Amounts are decimal strings ("10.00"), never numbers; precision per currency; times are RFC 3339 UTC with milliseconds.
- Wallet idempotency key is txnId: unique (merchantCode, txnId); a repeated txnId returns the first result, failures included.
- One wallet round (roundId) may contain several debits; never deduplicate by round + type.
- A rollback for a debit you never received returns TXN_NOT_FOUND and must be remembered so the late debit gets TXN_ROLLED_BACK.
- Never refuse a credit or rollback because the player is disabled. A credit of "0.00" closes the round and returns OK.
- Each Wallet API endpoint may only return the codes allowed for it; anything else is treated as result unknown.

## Get started

- [Introduction](index.html): Overview of the integration: the Platform API, the Wallet API and the onboarding materials.
- [Player launch flow](quickstart.html): How a player goes from the merchant's site into a game table.
- [Authentication](authentication.html): Request headers, HMAC-SHA256 signing, the test vector and IP whitelisting.
- [Signing SDKs](sdks.html): Ready-made signing and verification code for eight languages.

## Core concepts

- [Conventions](conventions.html): Transport, response envelope, amounts, time, idempotency and versioning.
- [Result codes](errors.html): Every result code, the codes allowed per endpoint and strict response validation.
- [Wallet rounds](wallet-model.html): The wallet round model, delivery guarantees, retries and transaction sequences.
- [Fund safety](fund-safety.html): Failure scenarios and the safeguards on both sides.
- [Reconciliation](reconciliation.html): Daily reconciliation and investigation of individual rounds.

## Platform API

- [Overview](merchant-api.html): Endpoints called by the merchant. Base URL https://<API_HOST>/merchant/v1.
- [Health](health.html): Liveness, maintenance status and our clock. No signature.
- [List games](games-list.html): The tables and lobby entries of one platform that are open to your account.
- [Launch a game](games-launch.html): A one-time launch URL for a player. The first launch of an extPlayerId creates the player on our side.
- [Round report URL](rounds-report-url.html): A one-time URL to a page showing one finished round: result, bets, wins and its wallet transactions.

## Wallet API

- [Overview](wallet-api.html): Endpoints implemented by the merchant under its callbackUrl and called by the platform.
- [Authenticate](wallet-auth.html): Called once during games/launch: exchange the launch token for the player.
- [Balance](wallet-balance.html): Read the player's balance (table entry, reconnect, refresh). Read only.
- [Debit](wallet-debit.html): Take a stake. Idempotent by txnId; one wallet round may contain several debits.
- [Credit](wallet-credit.html): Pay a settlement (may be 0). The closing credit carries roundClosed: true.
- [Rollback](wallet-rollback.html): Reverse exactly one debit, in full.

## Go live

- [Conformance test](testing.html): The fixed test suite run against the merchant wallet before go-live.
- [All test cases](test-cases.html): All cases of the conformance test, in execution order.
- [Go-live checklist](go-live.html): Items to confirm before going live.
- [Field glossary](glossary.html): Every field name used in this guide.
- [Changelog](changelog.html): Changes to the protocol and this guide.

## Optional

- [Signing SDK, Python](sdk/python/merchant_sign.py): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test
- [Signing SDK, Node.js](sdk/node/merchant-sign.js): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test
- [Signing SDK, Go](sdk/go/merchantsign/merchantsign.go): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test
- [Signing SDK, Java](sdk/java/MerchantSign.java): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test
- [Signing SDK, PHP](sdk/php/MerchantSign.php): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test
- [Signing SDK, C#](sdk/csharp/MerchantSign.cs): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test
- [Signing SDK, Ruby](sdk/ruby/merchant_sign.rb): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test
- [Signing SDK, bash + openssl](sdk/shell/merchant-sign.sh): sign requests to the Platform API and verify Wallet API requests; built-in test-vector self-test