Phoenix Games Integration

Phoenix Games provides casino games (Crash, Keno, Mines, Slots, etc.) that operators embed on their platform. The integration has two sides:

You implement webhook endpoints that Phoenix calls to move money (withdraw, deposit, rollback, balance check).

You call Phoenix's Operator API to generate game sessions, fetch bet history, and grant free bets.

The Bet Lifecycle

Every real-money bet follows this sequence:

Player places bet
    |
    v
Phoenix calls POST /withdraw on your server
    (deducts wager from player balance)
    |
    v
Game plays out
    |
    +---> Player wins
    |       Phoenix calls POST /deposit (credits winnings)
    |
    +---> Player loses
    |       Phoenix calls POST /deposit with amount: 0
    |
    +---> Bet cancelled / game error
            Phoenix calls POST /rollback (reverses the withdraw)

Every bet starts with a withdraw and ends with either a deposit or a rollback. Never both.

Key Concepts

Amounts are in cents. A 1000 in the request means 10.00 in the player's currency. All calculations must use integer arithmetic to avoid floating-point drift.

Every request is signed. Phoenix signs webhook requests with RSA-SHA256. You must verify the signature before processing. Details in Security.

Idempotency via tx_id. Every transaction has a unique tx_id. If you receive the same tx_id twice, return the same response without processing it again. This is the single most important requirement - failure here means double-charging players.

All responses use the same format:

{"type": "SUCCESS", "balance": 1234.56, "timestamp": 1712401234567}

or

{"type": "ERROR", "code": "INSUFFICIENT_BALANCE", "balance": 1234.56}

The balance field is a float (dollars, not cents). The timestamp is Unix milliseconds - used for ordering balance updates. Error responses should include balance when available. Always return HTTP 200 - the outcome is in the type field.

Integration Checklist

1. Generate RSA keys and register as an operator
2. Implement the 4 webhook endpoints (withdraw, deposit, rollback, player-balance)
3. Implement signature verification on all endpoints
4. Implement JWT token generation for game sessions
5. Embed games via iframe on your frontend
6. Run the self-service integration tester to validate