Disbursement statuses
The Payouts product reports a payout's lifecycle through these status values. They appear in Fund Transfer Status and the Payout S2S callback.
Non-terminal — keep polling
| Status | Meaning |
|---|---|
PROCESSING | Disbursement in progress. |
INCOMPLETE | Same as PROCESSING. |
PENDING | Same as PROCESSING. |
SENT_TO_BENEFICIARY | Initiated from source bank; awaiting confirmation from beneficiary bank. |
For any non-terminal status, query Fund Transfer Status again with backoff until you reach a terminal value, or wait for the S2S webhook.
Terminal — final state
| Status | Meaning | Action |
|---|---|---|
SUCCESS | Funds reached the beneficiary. | Mark payout completed. |
FAILED / FAILURE | The payout failed. error_message explains why. | Mark failed. Issue a fresh merchant_reference_number if retrying. |
RETURNED_FROM_BENEFICIARY | The source bank initiated successfully but the beneficiary bank rejected the credit. Funds are back in your disbursement balance. | Mark failed and either retry with corrected beneficiary details or refund the originating customer. |
tip
Treat only the terminal statuses as authoritative. A SENT_TO_BENEFICIARY can still flip to FAILED (rare) or SUCCESS — never mark a payout as complete on the strength of a non-terminal state.