Wallet contract
The one thing you implement. We call it while a game plays, for every provider we carry, so you integrate one contract instead of one per provider.
Money moves in one direction of calls: the game provider reports to Callisto Games, and Callisto Games calls your wallet. Your wallet never calls us and never talks to the provider. See integration flow →
Request
Request · we send
POST {your wallet_url}
Content-Type: application/json
X-Agg-Key-Id: ak_5f2c9e01a34b7d8e2f0c1b6a
X-Agg-Timestamp: 1759150800
X-Agg-Signature: hex_lowercase(HMAC_SHA256(secret, timestamp + "." + raw_body))
{
"action": "bet", // getbalance | bet | win | rollback
"transaction_id": "pragmatic:5501934", // the idempotency key; "" on getbalance
"reference_transaction_id": null, // rollback only: the movement being undone
"session_id": "2222aaaa-5b6c-4d7e-8f90-a1b2c3d4e5f6",
"round_id": "7200311", // the provider's round
"player_id": "p-1",
"game_id": "vs20fruitsw", // game provider code; null on getbalance
"currency": "EUR",
"amount": "1.50", // string; null on getbalance
"free_spins_id": "promo-7" // only on movements of a free-spin series
}| Field | Type | Description |
|---|---|---|
| action | string | getbalance, bet, win or rollback. One URL takes all four. |
| transaction_id | string | Our id for the movement: "<provider>:<provider id>". Treat the whole string as the id. It is the idempotency key. Empty on getbalance. |
| reference_transaction_id | string | null | On rollback: the movement being undone. |
| session_id | string | The session from POST /v1/sessions. Map it back to your player and the catalogue game you launched. |
| round_id | string | The provider's round. Always empty on getbalance, including the balance reads we make while settling a rollback. |
| player_id | string | Your reference, as sent to POST /v1/sessions. |
| game_id | string | null | The game provider's code for this round, not the catalogue id; null on getbalance. See Game identifiers. |
| currency | string | The session currency. |
| amount | string (money) | null | A decimal string in the currency's own precision. Null on getbalance. |
| free_spins_id | string | Only on bets, wins and rollbacks (the provider's or our own) of a free-spin series or a bonus campaign; left out otherwise. Every other field without a value is sent as null. |
Verify the signature
Same formula as your calls to us, with the secret of the key named in X-Agg-Key-Id, over the raw bytes of the body you received. Verify before parsing and refuse anything that does not match with INVALID_SIGNATURE. During a rotation either of your two keys may be named.
Response
| You answer | Body | What we do |
|---|---|---|
| 200 | { "balance": "98.50", "transaction_id": "op-4471" } | Done. balance (required, a string) is after the movement; transaction_id (optional, a string or a number) is your own id. |
| 200 on bet or win | { …, "bonus_amount": "0.50" } | Optional: the part of the amount that was bonus money. Reporting it can lower what you are charged; leave it out when there was none. |
| 4xx (not 408, 429) | { "error": "INSUFFICIENT_FUNDS", "message": "…" } | A refusal. Not retried; the provider is told. See Wallet errors. |
| 5xx, 408, 429, no answer | — | Silence. Retried, then rolled back. See Idempotency & retries. |
A 200 must carry a readable balance
A 200 whose body has no string balance (an error object, a number, HTML) is treated as silence, not as success or refusal: it is retried and then rolled back. bonus_amount and transaction_id are read as a string or a number; any other form counts as the field left out and does not undo a movement whose balance was readable. Refuse with a 4xx.