How payouts work — start to finish

The shape of a payout

When you tap Redeem, three things happen inside a single database transaction:

• Your account balance is locked.
• A debit ledger entry is appended for the redemption amount.
• A Payout row is created with status pending.

If any one of those fails, all three are rolled back. You cannot end up debited without a payout row, or have a payout row without a corresponding debit.

The state machine

A payout moves through four public states:

• pending — accepted; waiting for the processor.
• processing — handed off to the payment partner.
• paid — funds delivered.
• failed — the partner rejected the payout; your balance is automatically refunded.

In dev the processor is in-process and flips pending → processing → paid after a short delay. In production this is a queued worker.

Idempotency

Every redemption you submit from the web app carries an Idempotency-Key. Submit the same redemption twice and you get one payout, not two — the second request returns the original.

That's the whole story.