Statuses

Every payment, payout, and appeal returned by the API carries a status field that tells you where the object is in its lifecycle. This reference explains what each status means and which statuses are final.

How to read status

Each object moves through a set of statuses. At any moment its status is either:

Transitional — the object is still in flight and its status may change again.

Terminal — the status is final. The object has settled and will not change on its
own, so it is safe to stop tracking it.

A terminal status also carries an outcome: it can represent either a success or a failure. This distinction matters more to your integration than terminality alone — paid and declined are both final, but you handle them very differently.

The tables below list, for every status: whether it is terminal, its outcome (for terminal statuses), and a description.

Handling statuses

You can drive your entire integration from the two axes above:

Terminal, failure (declined, canceled, expired) — read the Status Codes to understand the cause and whether a retry makes sense.

Terminal, success (paid, partially_paid, overpaid, refunded, approved) reconcile the object. For partially_paid and overpaid, reconcile against the actual amount, which differs from the amount requested.

Compatibility

Only the statuses documented here are part of the public API contract. We may introduce new statuses over time. Design your integration to treat any status it does not recognize as transitional, and wait for a documented terminal status before acting. Always compare status values in lowercase.

Payment statuses

A payment settles in a single step: once processing finishes, its status reflects exactly how much money was received. A payment that receives less than the requested amount settles
as partially_paid and does not wait for the remainder.

Status	Terminal	Outcome	Description
`processing`	No	—	The requisite has been issued and the payer's transfer is awaited.
`paid`	Yes	Success	The full requested amount was received.
`partially_paid`	Yes	Success	Less than the requested amount was received, and the payment has settled at that amount.
`overpaid`	Yes	Success	More than the requested amount was received. This is recorded as-is, not treated as an error.
`partially_refunded`	No	—	Part of the received amount has been returned to the payer. May still advance to `refunded`.
`refunded`	Yes	Success	All received money has been returned to the payer.
`declined`	Yes	Failure	The payment was rejected. The `status_code` field explains why.
`canceled`	Yes	Failure	The payment was canceled before any money was received. The `status_code` field explains why.
`expired`	Yes	Failure	The payment was not completed before its time-to-live elapsed.

A settled payment (paid, partially_paid, overpaid) can still change later through a refund or the resolution of an appeal. These are deliberate, separate actions — the status will not change on its own.

Payout statuses

Payouts follow the same lifecycle as payments: a payout settles in a single step according to how much was actually paid out.

Status	Terminal	Outcome	Description
`processing`	No	—	The payout is being processed.
`paid`	Yes	Success	The full requested amount was paid out.
`partially_paid`	Yes	Success	Less than the requested amount was paid out, and the payout has settled at that amount.
`overpaid`	Yes	Success	More than the requested amount was paid out. Recorded as-is, not treated as an error.
`partially_refunded`	No	—	Part of the paid-out amount has been returned. May still advance to `refunded`.
`refunded`	Yes	Success	All paid-out money has been returned.
`declined`	Yes	Failure	The payout was rejected. The `status_code` field explains why.
`canceled`	Yes	Failure	The payout was canceled before any money was paid out. The `status_code` field explains why.
`expired`	Yes	Failure	The payout was not completed before its time-to-live elapsed.

Appeal statuses

An appeal is a dispute you open against a payment or payout. Casharc reviews it and reports the outcome through the appeal's status. When an appeal is approved, the resulting correction — an adjustment, a refund, or a reversal — is applied to the original payment or payout, which is why a settled object can change after a dispute.

Status	Terminal	Outcome	Description
`processing`	No	—	The appeal is being processed.
`approved`	Yes	Success	The appeal was accepted. The related payment or payout is corrected accordingly.
`rejected`	Yes	Failure	The appeal was denied. The `status_code` field explains why.
`canceled`	Yes	Failure	The appeal was canceled before a decision was reached. The `status_code` field explains why.

Status codes

When an object ends in declined, canceled, expired the status_code field identifies the cause. Status codes are stable, machine-readable values — build your logic against the code itself, not against its human-readable description, which may change.

See the Status Codes reference for the full list, including which codes are retriable.

How to read status#

Handling statuses#

Compatibility#

Payment statuses#

Payout statuses#

Appeal statuses#