Payout — це не “натиснули кнопку і відправили”
Виплати — найбільш ризиковий етап: гроші йдуть “назовні”, а провайдери відповідають асинхронно. Потрібні чіткі статуси і бухгалтерський підхід (ledger), інакше з’являються “втрати” та ручні розбори.
1) Модель станів
- created → pending_provider → processing → succeeded/failed.
- Окремо: reversed/chargeback/expired (за правилами провайдера).
2) Ledger (подвійний запис)
- Операція виплати = дебет/кредит між рахунками.
- Баланс — це агрегат ledger, а не “поле balance”.
3) Webhooks і ретраї
- Валідація підпису, дедуплікація по eventId.
- Idempotency key на створення payout.
4) Reconciliation
Регулярно звіряй ledger зі звітами/експортом провайдера, фіксуй розбіжності і роби керований re-sync.
Підсумок
Payouts мають бути побудовані як фінансова система: ledger + статуси + webhooks + reconciliation. Це зменшує ризик інцидентів і робить операції прогнозованими.