Settlement
How payouts reach your players after a result, and what to do when your wallet refuses one
When a market's result is entered (or it is voided), Phoenix works out each player's payout and credits it through your wallet. Watch it until every payout is paid.
Settlement is a workflow
The result decides who wins. Settlement is the payouts reaching your players' wallets.
What Happens
- A result is entered, or the market is voided.
- Phoenix records the winning outcome, or the void and its basis.
- Phoenix works out each position's payout or refund, rounded down to your currency's smallest unit.
- The market shows Settled (or Void, or Settled 50/50).
- Phoenix sends your wallet one
credit_cashper position: its payout or refund (and, under wallet API 1.1, a zero credit for a position that pays nothing). On the Events list the event shows Settling until every payout is paid.
Payouts are sent in the background and retried on temporary failures, so a large market can take a little while to settle. Each operator's book settles on its own: your players' payouts depend only on your wallet.
Refused Payouts
If your wallet refuses a payout (a 4xx other than 408, 409 or 429, a redirect, or a rejected answer; for example player_not_found for a closed account), Phoenix sends it again with growing delays, up to five minutes apart, and stops once your wallet has refused it for 24 hours. The payout then shows as Refused, with your wallet's own reason, on Trades, on the trade's detail, on the player's page and in Finance > Wallet moves. That market's settlement for your operator stays incomplete.
A temporary problem (a timeout, a connection error, 408, 409, 429 or a 5xx) never stops the retries: they continue with growing delays, up to five minutes apart. A payout Phoenix did not send, because one of its own rules refused it (for example the wallet URL is not a public https URL), is not a refusal: it stays Owed and is sent again, and it never stops on its own.
There is no retry button in the back office. To recover a refused payout:
- Fix the cause in your wallet (for example, reopen the account).
- Tell Phoenix the player id and the order or payout. Phoenix resends it, or marks it resolved off-platform if you paid the player another way.
Ask your developers to make sure your wallet never refuses a payout in normal operation (see credit_cash).
Payout Status
On Trades, a settled position's payout is one of:
| Status | Meaning |
|---|---|
| Paid | Your wallet accepted the credit |
| Owed | Still being sent, including a payout Phoenix could not send under its own rules |
| Refused | Your wallet kept refusing it for 24 hours; see above |
| Resolved off-platform | Phoenix marked it settled outside the wallet, at your request |
| Nothing to pay | The position lost, or was sold before the end, so there is no payout |
What to Watch
- Events that stay in Settling on the Events list for long.
- Any payout shown as Refused.
- Voided markets whose refunds have not all been paid.
- Players asking about a payout they expected.
Support Checklist
When a player asks about a settled prediction:
- Open Players and find the player by your player id.
- Open Positions and find the market; check the result and the position's payout.
- Open the trade: Payout state shows Paid, Owed or Refused.
- Read the Operator wallet moves and their Key (the idempotency key), and find the same key in your wallet.
- Escalate to Phoenix when the back office, Phoenix's records and your wallet disagree.
Your wallet ledger should be able to answer: "Did this payout reach the player's balance exactly once?"