> ## Documentation Index
> Fetch the complete documentation index at: https://www.marqeta.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle of a Dispute

This guide navigates a simple dispute lifecycle in sandbox, while simulating the network state transitions to help you:

* Create a dispute by submitting an API request or by using the Marqeta Dashboard, upload supporting documents, and prepare it for chargeback submission to the card network.
* Submit a dispute for chargeback and manually transition card network states as they occur in a production environment.

You will also learn how Marqeta and network dispute states relate to each other as a dispute moves through its lifecycle.

<Note>
  This guide uses a minimal configuration Mastercard cleared transaction as an example.
</Note>

# Prerequisites

Before you initiate the dispute process, ensure that you have the following in place:

* A cleared transaction
* A webhook handler

<Note>
  For more information about setting up a webhook handler, see [Set Up a Webhook Handler](/docs/developer-guides/disputes-sandbox/disputes-webhook-handler/).
</Note>

# Dispute state flow

A Marqeta state is assigned when a dispute is first created, and a card network state is assigned when the dispute is submitted to the card network. The states transition as a dispute progresses towards resolution. The sandbox does not connect to the card networks. However, in production, you will use the `DISPUTE` value in the `type` field for integrated network disputes, and `LEGACY_DISPUTE` for non-integrated cases.

In production, Marqeta handles all network-side state transitions once a chargeback is submitted. This guide include steps to simulate the network-side state transitions to illustrate the transitions that occur automatically.

To simulate the network-side transitions, use the `LEGACY_DISPUTE` value in the `type` field of the request payload. This allows you to manually transition the dispute through the card network states by simulating the process of submitting the disputes to card network to better understand the process. See [Submit a Dispute](/docs/developer-guides/disputes-sandbox/disputes-sandbox-submit-manage/#submit-a-dispute).

The following table outlines how Marqeta and network states relate to each other.

| Marqeta State | Network State |
| :- | :- |
| OPEN | - |
| OPEN\_WITH\_ACTION\_REQUIRED | - |
| READY | - |
| CHARGEBACK\_INITIATED | `initiated` |
| CHARGEBACK\_INITIATED | `representment` |
| CHARGEBACK\_INITIATED | `prearbitration` |
| CHARGEBACK\_INITIATED | `arbitration` |
| CLOSED | `case_won` |
| CLOSED | `case_lost` |
| CLOSED | `network_rejected` |

The following diagram illustrates the states a dispute transitions through during its lifecycle.

<Frame>
  <div className="not-prose" style={{overflowX: 'auto', minWidth: '600px'}}>
    ```mermaid theme={null}
    %%{init: {
    'state': { 'useMaxWidth': true },
    'themeVariables': {
      'nodeSpacing': 20,
      'rankSpacing': 20,
      'padding': 10
    }
    } }%%
    stateDiagram-v2
    direction TB

    state "OPEN" as OPEN
    state "OPEN_WITH_ACTION_REQUIRED" as ACTION
    state "READY" as READY

    state "CHARGEBACK_INITIATED" as CI {
      direction TB
      Initiated
      Representment
      Prearbitration
      Arbitration
    }

    state "CLOSED" as CLOSED {
      direction TB
      CW: Case Won
      CL: Case Lost
      NR: Network Rejected
    }

    %% Logic Flow
    [*] --> OPEN
    OPEN --> ACTION
    ACTION --> READY
    READY --> CI
    CI --> CLOSED
    CLOSED --> [*]
    ```
  </div>
</Frame>


## Related topics

- [About Disputes](/docs/developer-guides/about-disputes.md)
- [About Credit Account Disputes](/docs/developer-guides/about-credit-account-disputes.md)
- [About the Disputes Portal](/docs/developer-guides/about-disputes-portal.md)
- [Disputes Tutorial Overview](/docs/developer-guides/disputes-sandbox/disputes-sandbox-overview.md)
- [Dispute Webhook Events](/docs/developer-guides/dispute-webhook-events.md)