Dispute state machine

Dispute stages and statuses modeled as a state machine, with the valid transitions between them.

A dispute is best understood as a state machine. It has a stage (where the case sits in the network's escalation path) and a status (whether it is waiting on you, under review, or resolved). Chargeflow unifies stages and statuses across every connected PSP so you read one consistent model regardless of source. This page lists the states and the transitions allowed between them.

Stages

The stage tracks how far a dispute has escalated within the card network's rules. Each stage calls for a different approach, and Chargeflow takes stage-appropriate action.

Stage	What happens	What Chargeflow does	Possible next stage
`inquiry`	Also called a retrieval or request for information (RFI). The issuer requests transaction documents instead of immediately issuing a chargeback.	Sends available transaction documents to the issuer to prevent escalation, lists any missing artifacts as a prioritized checklist, and notifies your team.	The issuer can escalate to `chargeback`.
`chargeback`	The issuer posts a provisional reversal and notifies the acquirer or PSP. The disputed amount is provisionally removed from the merchant's balance.	Normalizes the dispute data, creates the case record, consolidates and enriches evidence, drafts a targeted rebuttal, and flags missing high-impact artifacts.	One party can escalate to `pre_arbitration` to reopen the case as a second chargeback.
`pre_arbitration`	Also called a second chargeback. One party (merchant or buyer) challenges the issuer's decision and requests escalation under network rules. This may incur fees.	Rebuilds the case narrative for escalation, compiles supplemental evidence, and advises on likelihood versus cost.	`arbitration`, a final decision by the network.
`arbitration`	Final adjudication by the card network. The network issues a binding decision and any applicable fees. Arbitration is rare and can be slow and costly.	Prepares network-specific documentation, submits materials, and logs the outcome and fees.	None. The decision is binding.

Stage transitions

inquiry ──> chargeback ──> pre_arbitration ──> arbitration

A dispute can enter directly at chargeback when the issuer skips the inquiry step. Stages only move forward; a dispute never returns to an earlier stage.

Statuses

The status tells you what the dispute needs right now, independent of its stage. A dispute can be in needs_response at the chargeback stage, then move to under_review after submission, then settle as won or lost.

Status	Description	Possible actions
`needs_response`	The dispute requires a response from the merchant. Chargeflow prepares to submit a rebuttal unless you add targeted evidence first.	Add targeted evidence with the Update Dispute endpoint before Chargeflow submits the rebuttal on your behalf.
`under_review`	The dispute has been submitted, or the response window has passed, and the issuer is evaluating the case.	None. Wait for the decision.
`won`	The dispute was resolved in the merchant's favor.	None. Funds are returned.
`lost`	The dispute was resolved in the buyer's favor.	Consider escalation to `pre_arbitration` only after a cost-benefit review. Contact Chargeflow for guidance before escalating.

Status transitions

From	To	Trigger
`needs_response`	`under_review`	The rebuttal is submitted, or the response window closes.
`under_review`	`won`	The issuer rules in the merchant's favor.
`under_review`	`lost`	The issuer rules in the buyer's favor.
`lost`	`needs_response`	The case is escalated to `pre_arbitration` and reopens for a new response.

Stage and status move independently

Stage describes escalation within the network. Status describes who the case is waiting on. A single dispute carries both at once, and they advance on their own triggers.

Next steps

Chargeback lifecycleThe end-to-end flow and the parties involved.Representment and evidenceWhat to submit during needs_response.Reason codesHow disputes are categorized.WebhooksTrack status changes programmatically.