Problem
Paystack payments, bank transfers, internal ledger postings, and Stellar transactions have different confirmation and reversal semantics. Treating provider success as immediate final settlement risks double credit, premature payout, and inconsistent user balances.
Scope
- Define a canonical settlement state machine covering initiated, provider-pending, observed, provisionally credited, confirmed, reversed, disputed, failed, and expired.
- Map every Paystack event and Stellar ledger outcome to explicit transitions.
- Separate available, pending, held, and reversed balances.
- Establish finality thresholds and timeout/escalation rules per rail and environment.
- Require idempotency and causal links among provider reference, ledger journal, Stellar hash, pool investment, and user transaction.
- Compensate through reversal journals, never in-place balance edits.
- Add an operator timeline explaining why a settlement is stuck and which actions are safe.
Acceptance criteria
- Duplicate or reordered events cannot double-credit.
- Payout/investment eligibility uses confirmed funds only.
- Reversals preserve a complete audit trail and never create negative available balance silently.
- Cross-rail correlation is one-to-one or explicitly modeled as split settlement.
- Stuck states generate actionable alerts.
Required tests
Out-of-order webhooks, delayed bank transfer, Stellar failure after submission, provider reversal, partial split, duplicate reference, timeout, and concurrent verifier/webhook processing.
Non-goals
Do not replace provider-specific adapters; normalize their outcomes.
Problem
Paystack payments, bank transfers, internal ledger postings, and Stellar transactions have different confirmation and reversal semantics. Treating provider success as immediate final settlement risks double credit, premature payout, and inconsistent user balances.
Scope
Acceptance criteria
Required tests
Out-of-order webhooks, delayed bank transfer, Stellar failure after submission, provider reversal, partial split, duplicate reference, timeout, and concurrent verifier/webhook processing.
Non-goals
Do not replace provider-specific adapters; normalize their outcomes.