Payout Status
Avvio defines a strict 5-state vocabulary for payouts. Your internal database and ledger transitions should align with these states.
The Canonical Status Vocabulary#
| Status | Meaning | Impact on Your Balance | Terminal? |
|---|---|---|---|
pending |
Accepted and registered. Reserved, but not yet sent to the clearing rail. | Held (Reserved) | No |
processing |
Dispatched to the payment network or clearing house. Committed. | Committed | No |
completed |
The beneficiary was successfully credited by their bank. | Sent | Almost (See Bank Returns below) |
failed |
Not paid, or paid and subsequently returned by the bank. Inspect failureCode. |
Released back to balance (if debited) | Yes |
canceled |
Canceled before dispatch. Carries fundsReturned: true. |
Released back to balance | Yes |
State Transitions#
┌───────────────┐
│ pending │
└───┬───────┬───┘
│ │
│ ▼
│ ┌───────────────┐
│ │ canceled │
│ └───────────────┘
▼
┌───────────┐
│processing │
└──┬──────┬─┘
│ │
▼ ▼
┌───────────┐ ┌───────────┐
│ completed │ │ failed │
└─────┬─────┘ └───────────┘
│ (Bank Return)
└─────────▲The Bank Return Edge Case (completed → failed)#
completed is not absolutely irrevocable. In cross-border banking, a receiving bank can accept and credit a payment, and then return or reject it several days later due to account freeze, name mismatch, or regional compliance. When this occurs, the payout transitions from completed to failed with:
>
-status: "failed"-failureCode: "returned_by_bank"-fundsReturned: true
>
Never build an internal ledger that treatscompletedas immutable. Continue processing event stream updates (GET /events?since=) for settled payouts.
The fundsReturned Flag#
When a payout enters failed or canceled, the fundsReturned boolean answers the single question your finance team needs:
fundsReturned: true: The debited USD amount has been credited back to your balance.fundsReturned: false: The funds did not return (e.g.compliance_rejectedor regulatory seizure).
Failure Codes#
When status is failed, inspect the failureCode property:
quote_expired · insufficient_funds · limit_exceeded · account_invalid
account_cannot_receive · compliance_rejected · authorization_not_completed
returned_by_bank · execution_failed · unknownIf an unrecognized code appears in the future, treat it functionally as execution_failed.
Informational stage Property#
Slow settlement rails may include an optional stage field (awaiting_details, under_review, settling). This is for support transparency only ("where is my payment?"). Do not branch automated ledger transitions on stage.
Status Transition State Machine
completed can still transition to failed if the destination bank returns the funds days later.