Jump to Content

Payout Status

Understand Avvio's strict 5-state payout lifecycle, state transitions, and how to handle bank return edge cases.

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 treats completed as 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_rejected or 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 · unknown

If 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.

Updated about 2 hours ago

Did this page help you?