Casino API

These routes do not accept customer_id, a provider player id, provider credentials, or a return URL. Unknown JSON fields are rejected. Launch and wallet bodies are limited to 8 KiB.

Bonuses, jackpots, free spins, and promotions are not part of this API. There is no public transaction-status route.

{
  "url": "https://games.example/launch/session"
}

curl -sS -X POST "https://api.hzura.com/api/v1/casino/games/DS-example/launch" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","currency":"EUR","device":"desktop","mode":"real"}'

{
  "player_id": "player-1",
  "currency": "EUR",
  "language": "en-US",
  "device": "desktop",
  "mode": "real"
}

language on the body only filters which game can be launched, the same way the games query does. The locale sent to the provider is the locale stored on the player: the customer's configured locale, or the server locale when the customer has none. en-US and en_US are the same locale and are sent as en_US. A two-letter code such as en is not a launch language. If no ll_RR locale can be resolved, launch is rejected and a new player is not created.

When device is omitted, desktop is used if the game lists desktop or lists no device. Otherwise mobile is used when the game lists it. If neither can be chosen, the game is game_not_available.

Country and currency are taken from the customer's casino configuration on the first launch, then stored on the player. A later launch cannot switch them. currency in the body must match that stored value, ignoring case. The value persisted is uppercase.

There is no separate create-player route. The first launch that passes validation stores player_id for this customer. Later launches and every wallet call reuse that id.

The same player_id at another customer is a different player. One customer cannot read or move another customer's player.

The wallet does not create a player. Call launch before BALANCE, DEBIT, CREDIT, or ROLLBACK. A launch that fails after the player row is stored still leaves that mapping in place. Repeat the launch with the same player_id.

One route covers every wallet operation. operation is exactly BALANCE, DEBIT, CREDIT, or ROLLBACK. The balance is the HZURA wallet for that player. BALANCE does not call the game provider and creates the wallet at zero on the first read if the player exists and no wallet row exists yet.

Success responses always include operation, status, currency, and balance. balance is decimal text with trailing zeros removed, so 5.00 is "5" and 12.50 is "12.5". transaction_id is present on transfer results and is the caller's idempotency key, not an internal row id. BALANCE omits it.

status is success for a completed read or transfer. Replaying an original transaction that has since been reversed returns rolled_back.

{
  "operation": "DEBIT",
  "status": "success",
  "currency": "EUR",
  "balance": "7.5",
  "transaction_id": "bet-1001"
}

The balance is reduced before the provider is called. If the balance cannot cover the amount, the response is insufficient_balance and the provider is not called.

On provider acceptance the reduced balance stands. A definite provider rejection releases that reservation and returns wallet_provider_failed. A timeout leaves the debit pending and keeps the reserved amount.

curl -sS -X POST "https://api.hzura.com/api/v1/casino/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","operation":"DEBIT","transaction_id":"bet-1001","amount":"5.00","currency":"EUR"}'

If the wallet held 12.5 before this debit, a successful response looks like this. amount "5.00" is stored and returned in balance without trailing zeros.

{
  "operation": "DEBIT",
  "status": "success",
  "currency": "EUR",
  "balance": "7.5",
  "transaction_id": "bet-1001"
}

The balance increases only after the provider accepts the credit. A rejection or a timeout does not credit the wallet. A timeout still leaves the transaction_id pending.

curl -sS -X POST "https://api.hzura.com/api/v1/casino/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","operation":"CREDIT","transaction_id":"win-1001","amount":"12.50","currency":"EUR"}'

{
  "operation": "CREDIT",
  "status": "success",
  "currency": "EUR",
  "balance": "12.5",
  "transaction_id": "win-1001"
}

Rollback reverses one successful DEBIT or CREDIT for the same player, currency, and amount. transaction_id is the rollback's own idempotency key. reference_transaction_id is the original debit or credit. The amount must equal the original amount; a mismatch is 400 invalid_wallet.

A debit is restored only after the provider accepts the rollback. A credit is reserved first and restored to the player only if the provider rejects the rollback. If that reservation cannot be taken, the response is insufficient_balance.

A second rollback of the same original transaction, under a new key, is wallet_already_rolled_back. Repeating the rollback key with the same body returns the first rollback result. Pending and failed originals cannot be rolled back (wallet_transaction_not_reversible). An unknown reference is wallet_transaction_not_found.

curl -sS -X POST "https://api.hzura.com/api/v1/casino/wallet" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player_id":"player-1","operation":"ROLLBACK","transaction_id":"rb-1001","reference_transaction_id":"bet-1001","amount":"5.00","currency":"EUR"}'

{
  "operation": "ROLLBACK",
  "status": "success",
  "currency": "EUR",
  "balance": "12.5",
  "transaction_id": "rb-1001"
}

transaction_id is unique per customer. Repeating the same key with the same player, operation, amount, and currency returns the original result and does not call the provider again. For a rollback, the reference and amount must match as well.

504 wallet_provider_timeout means the provider did not answer and the outcome is unknown. The transaction stays pending. A pending debit keeps the reserved amount. A pending credit is not applied. Repeating the same transaction_id does not move the balance again.

Do not start a second debit or credit for the same bet with a new transaction_id while the first one is pending. That would be a different transaction. Rollback of a pending transaction is rejected.

This API does not look up a provider status for that row. Customers cannot settle a pending transaction through a public route. A timeout is not success.

• Error referenceWallet, launch, and idempotency codes with their messages.
• AuthenticationWhy casino calls need an API key.