Reconciliation
Match Phoenix wallet callbacks to the operator ledger
Reconciliation proves that Phoenix Prediction wallet callbacks and the operator wallet ledger agree.
The practical question is simple: every Phoenix Prediction tx_id should affect the operator wallet exactly once.
What to Store
For every debit, credit, and rollback callback, store:
| Field | Why |
|---|---|
tx_id | Idempotency and lookup key |
player_id | Operator-side player account |
amount | Wallet movement amount |
kind | Debit, credit, or rollback |
game | Should be prediction_market_v1 |
action_id | Groups related bet and settlement actions |
market_id or round_id | Market or round reference when present |
| Request body | Audit and support |
| Response body | Proves what your wallet returned |
| Final balance | Support and accounting |
| Signature result | Security audit |
| Processed timestamp | Ordering and investigation |
Daily Reconciliation
Run these checks at least daily during launch:
- Count Phoenix debit callbacks vs accepted wallet debits.
- Count Phoenix credit callbacks vs settled wallet credits.
- Find duplicate
tx_idrequests and confirm they had one balance effect. - Find credit callbacks that failed after retries.
- Compare total debit amount, total credit amount, and net GGR.
- Review voided market refunds.
Player Support Flow
When a player asks about a prediction:
- Find the player by your
player_id. - Find Phoenix Prediction wallet transactions by
tx_id,action_id, or market reference. - Confirm whether debit was accepted.
- Confirm whether the market settled or voided.
- Confirm whether credit or refund was applied.
- Compare final balance with your wallet ledger.
Do not rely only on iframe UI state for wallet support. The operator wallet ledger is the financial source of truth.
Common Mismatches
| Symptom | Likely cause |
|---|---|
| Player charged twice | Duplicate debit tx_id was not idempotent |
| Player missing payout | Credit endpoint failed or returned a terminal error |
| Player sees settled market but wallet not updated | Credit delivery is still retrying or blocked |
| Operator ledger has unknown Phoenix transaction | Missing request logging or shared wallet endpoint reuse |
| Phoenix reports wallet error | Callback returned non-2xx, timed out, or rejected unexpectedly |
Launch Recommendation
During the first production rollout, reconcile more often than usual. Prediction markets create new support questions because players are watching open positions, market close, resolution, and wallet settlement as separate moments.