Statuses and accounting

Statuses

Status	Meaning	Vendor action
pending	Provider accepted; payment not yet confirmed	Keep the hold and poll
paid	Payment confirmed	Finalise the debit and deliver the value
failed	Definitive rejection; gateway reservation released	Release the customer's hold
reversed	Provider reversal recorded	Reconcile with finance before crediting
needs_review	Not confirmed, including queued or uncertain items	Keep the hold and poll; contact operations if unresolved
cancelled	Operator cancelled before submission	Release the customer's hold

Only paid completes a withdrawal. Queued batch items also appear as needs_review until processed; that status does not always mean an operator has started investigating. There is no vendor cancellation endpoint.

GET /payouts/{reference} reads stored state. Background workers perform status checks; the GET does not make a fresh provider request or submit a payment. OTT cash and bank payments are monitored for 30 days after payment. Vouchers never return pending; unresolved voucher outcomes remain needs_review. Paid vouchers are not polled automatically. A voucher reversal requires an explicit operator status check or verified manual reconciliation.

After a voucher timeout or conflict, retain the hold and poll the original payout reference. Recovery reads Flash's existing transaction by UUID, or its exact merchant-reference lookup if no UUID was stored. It never purchases again. A missing or ambiguous lookup is not proof of failure and leaves funds held. Reversals do not automatically credit the vendor balance.

Accounting boundary

Your prefunded gateway balance and your customer's balance are separate ledgers. The gateway reserves amount + fee for each payout, consumes the reservation on payment, and releases it on definitive failure or cancellation. Pending and uncertain payouts keep their reservations. Reversal credits require finance reconciliation. In your own ledger, hold the customer's balance once, finalise on paid, and release on failed or cancelled. Do not pay the same entitlement through two channels.