# Dispute state machine (https://docs.chargeflow.io/docs/reference/concepts/dispute-state-machine)



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 [#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 [#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 [#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 [#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. |

<Callout type="info" title="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.
</Callout>

## Next steps [#next-steps]

<Cards>
  <Card title="Chargeback lifecycle" href="/docs/reference/concepts/chargeback-lifecycle">
    The end-to-end flow and the parties involved.
  </Card>

  <Card title="Representment and evidence" href="/docs/reference/concepts/representment-and-evidence">
    What to submit during `needs_response`.
  </Card>

  <Card title="Reason codes" href="/docs/reference/concepts/reason-codes">
    How disputes are categorized.
  </Card>

  <Card title="Webhooks" href="/docs/reference/concepts/webhooks">
    Track status changes programmatically.
  </Card>
</Cards>