Getting started

What you receive from TALOS, what you need to configure and the recommended order to integrate.

What you receive#

Item	What it is for
Merchant code	Goes in the `X-Merchant-Id` header of every request and arrives in the same header of the callbacks.
Merchant secret	HMAC-SHA256 key (both directions). It is shown only once when created; if a new one is generated, the previous one stops working.
Merchant currency	The operation currency (BRL, MXN, ARS, COP, CLP, PEN or USD). One merchant = one currency.
Brand (`brand`)	The merchant group code; it is the sportsbook SDK `brand_id`. It is also returned by `GET /v1/merchant`.
API URL	Base of the environment `/v1/...` routes.

Keep the secret on the server

The secret signs requests that move money. Never put it in the browser, in the mobile app or in the repository: use an environment variable or a secrets manager.

What you tell TALOS#

Wallet URL (walletUrl) — the HTTPS endpoint that will receive the wallet callbacks. Without it, real-money launches return WALLET_NOT_CONFIGURED.
Your server outgoing IPs — TALOS can restrict your merchant API to an IP list. Calls from another IP get IP_NOT_ALLOWED.
Default language — used when the launch has no lang.
Products — slots, live casino and/or sportsbook.

Operating in several currencies#

Each currency is its own merchant (with its own code and secret), all in the same group — that is why the sportsbook brand, theme and layout are the same. On your server, pick the merchant by the player's currency:

TypeScript

// one code/secret pair per currency, from environment variables
const MERCHANTS = {
  BRL: { code: process.env.TALOS_MERCHANT_BRL!, secret: process.env.TALOS_SECRET_BRL! },
  MXN: { code: process.env.TALOS_MERCHANT_MXN!, secret: process.env.TALOS_SECRET_MXN! }
}

The wallet can be the same URL for all merchants: the callback carries the X-Merchant-Id and the currency, and it is signed with that merchant's secret.

Integration checklist#

Sign a simple call: GET /v1/merchant must return your code, currency and brand. See Authentication.
Implement the wallet endpoint with the balance, bet, win, refund and rollback actions, idempotent by tx_id. See Seamless wallet.
Validate the callback signature before touching the balance.
Launch a game with POST /v1/game/launch and play a few rounds; check the transactions in GET /v1/transactions.
Test reversals: a bet rejected for lack of balance, a refund of an applied bet and a refund of a bet you never received (TRANSACTION_NOT_FOUND).
If you have the sportsbook: embed it with the SDK and handle session renewal and the login button.
Reconcile the GGR report against your own ledger.