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

# Submit a Dispute

Once the dispute enters the `READY` state, you can submit it to the card network for processing. Submitting the dispute formally initiates the chargeback with the card network.

<Warning>
  **Caution**<br />In production, Marqeta handles all network-side state transitions once a chargeback is submitted. To simulate the card transitions once the dispute is submitted, you will call the `/disputetransitions` endpoints. This endpoint is not used in the production environment. This guide includes the following steps only to illustrate the transitions that occur automatically.
</Warning>

## Submitting a dispute to the card network

After reviewing the dispute case in a `READY` state, Marqeta submits it to the card network and the case transitions to the `CHARGEBACK_INITIATED` network state.

You can simulate submitting a dispute using a `POST  /cases/<case_token>/transitions` request. The chargeback can be initiated for a **provisional credit** or **no credit** flow.

The example below demonstrates a no-credit chargeback flow by sending `CHARGEBACK_NO_CREDIT` in the `action` field.

### Sample request body

<Accordion title="Sample request" defaultOpen>
  <CodeGroup>
    ```bash Curl theme={null}
        curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/transitions" \
            -H "X-Marqeta-Program-Short-Code: your-program-code" \
            -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
            -H "Content-Type: application/json" \
            -d '{
                "action": "CHARGEBACK_NO_CREDIT",
                "reason_code": "29",
                "created_by": "Your Name"
            }'
    ```

    ```javascript JavaScript theme={null}
        const initiateChargebackNoCredit = async (caseToken) => {
            const url = `https://your-subdomain.marqeta.com/v3/cases/${caseToken}/transitions`;

            const payload = {
                action: "CHARGEBACK_NO_CREDIT",
                reason_code: "29",
                created_by: "Your Name"
            };

            const response = await fetch(url, {
                method: 'POST',
                headers: {
                    'X-Marqeta-Program-Short-Code': 'your-program-code',
                    'Authorization': 'Basic YOUR_BASE64_ENCODED_STRING',
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
            });
    const data = await response.json();
            console.log('Chargeback Initiated:', data);
        };
    ```

    ```python Python theme={null}
        import requests

        case_token = "<case_token>"
        url = f"https://your-subdomain.marqeta.com/v3/cases/{case_token}/transitions"

        headers = {
            "X-Marqeta-Program-Short-Code": "your-program-code",
            "Authorization": "Basic YOUR_BASE64_ENCODED_STRING",
            "Content-Type": "application/json"
        }

        payload = {
            "action": "CHARGEBACK_NO_CREDIT",
            "reason_code": "29",
            "created_by": "Your Name"
        }

        response = requests.post(url, headers=headers, json=payload)

        print(f"Status: {response.status_code}")
        print(response.json())
    ```

    ```java Java theme={null}
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;
    public class ChargebackNoCredit {
            public static void main(String[] args) throws Exception {
                String caseToken = "<case_token>";
                HttpClient client = HttpClient.newHttpClient();
                String jsonBody = """
                    {
                        "action": "CHARGEBACK_NO_CREDIT",
                        "reason_code": "29",
                        "created_by": "Your Name"
                    }
                    """;

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://your-subdomain.marqeta.com/v3/cases/" + caseToken + "/transitions"))
                    .header("X-Marqeta-Program-Short-Code", "your-program-code")
                    .header("Authorization", "Basic YOUR_BASE64_ENCODED_STRING")
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                    .build();

                HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
                System.out.println("Result: " + response.body());
            }
        }
    ```
  </CodeGroup>
</Accordion>

### Sample response body

<Accordion title="Sample response" defaultOpen>
  <CodeGroup>
    ```json JSON theme={null}
    {
        "case_token": "<case_token>",
        "token": "3518f614-1ea4-4913-9002-639e21ce0f93",
        "reason_code": "29",
        "reason_description": "Chargeback with no Credit",
        "created_by": "Your Name",
        "from_state": "READY",
        "state": "CHARGEBACK_INITIATED",
        "action": "CHARGEBACK_NO_CREDIT",
        "created_date": "2026-03-09T19:26:35Z"
    }
    ```
  </CodeGroup>
</Accordion>

Upon submission, the dispute case transitions to the `CHARGEBACK_INITIATED` Marqeta state and the `initiated` network state.

<Note>
  **Note**<br />If the network rejects the submission, the dispute enters the `network.rejected` network state and the Marqeta state transitions to `CLOSED`. You can review the case and resubmit it with corrected details.
</Note>

When a dispute is submitted and enters a chargeback state, the Marqeta platform triggers specific webhooks. The exact webhooks depend on whether the the action involves a **provisional credit** or **no credit** flow. The `reason_code` used must match the action being performed.

Test your webhook handlers based on the selection you make from the following options.

If you select the `CHARGEBACK_CREDIT` action for provisional credit, the following webhook events are sent:

* `transactions.authorization.clearing.chargeback`
* `chargebacktransitions.initiated`
* `transactions.authorization.clearing.chargeback.provisional.credit.`

If you select the `CHARGEBACK_NO_CREDIT` action for no credit, the following webhook events are sent:

* `transactions.authorization.clearing.chargeback`
* `chargebacktransitions.initiated.`

<Note>
  **Note**<br />There can be a delay between the time an action is taken and when the webhook is sent. This is true for all webhooks.
</Note>

### Dispute identifiers

Marqeta and the card network identify a dispute using different tokens, as described below:

* **Case creation**: When a case is created, you have the reason code, and your primary identifier is the transaction token. This is the identifier Marqeta uses to identify the dispute.
* **Chargeback initiation**: When a chargeback is initiated on the network, you receive both the transaction token and the chargeback token. The card network uses the chargeback token to identify the dispute.

### Recommended actions

To effectively track and manage chargebacks, Marqeta recommends that you:

* **Maintain a mapping**: Store the relationship between the reason code and the transaction token within your system.
* **Link the identifiers**: Once a chargeback is initiated, use the chargeback token to tie the network event back to the original transaction token.
* **Associate the reason code**: Ensure the reason code is associated with the chargeback token for future tracking.

<Note>
  **Note**

  * The chargeback token will be the identifier that is sent throughout the lifecycle of disputes in all subsequent webhooks.
  * There can be multiple disputes associated with a transaction. Hence, the chargeback token is the right identifier to map to a reason code.
</Note>

## Providing provisional credit

Granting provisional credit is required if your program is subject to specific regulations. You are responsible for providing this credit if your program manages the ledger via Just-in-Time (JIT) funding.

For this example, which uses the `CHARGEBACK_NO_CREDIT` action, the system does not require provisional credit. However, this section provides an example of requesting provisional credit below for reference.

### Sample request body

<CodeGroup>
  ```bash Send a POST request theme={null}
  curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/actions" \
  -H "X-Marqeta-Program-Short-Code: your-program-code" \
  -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
  -H "Content-Type: application/json" \
  -d '{
      "action_type": "GRANT_PROVISIONAL_CREDIT",
      "created_by": "Your Name"
  }'
  ```

  ```javascript JavaScript theme={null}
  const grantProvisionalCredit = async (caseToken) => {
      const url = `https://your-subdomain.marqeta.com/v3/cases/${caseToken}/actions`;

      const payload = {
          action_type: "GRANT_PROVISIONAL_CREDIT",
          created_by: "Your Name"
      };

      const response = await fetch(url, {
          method: 'POST',
          headers: {
          'X-Marqeta-Program-Short-Code': 'your-program-code',
          'Authorization': 'Basic YOUR_BASE64_ENCODED_STRING',
          'Content-Type': 'application/json'
          },
          body: JSON.stringify(payload)
      });

      const data = await response.json();
      console.log('Provisional Credit Status:', data);
  };
  ```

  ```python Python theme={null}
      import requests
  case_token = "<case_token>"
      url = f"https://your-subdomain.marqeta.com/v3/cases/{case_token}/actions"

      headers = {
          "X-Marqeta-Program-Short-Code": "your-program-code",
          "Authorization": "Basic YOUR_BASE64_ENCODED_STRING",
          "Content-Type": "application/json"
      }
  payload = {
          "action_type": "GRANT_PROVISIONAL_CREDIT",
          "created_by": "Your Name"
      }
  response = requests.post(url, headers=headers, json=payload)
  print(f"Status: {response.status_code}")
      print(response.json())
  ```

  ```java Java theme={null}
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpRequest.BodyPublishers;
  import java.net.http.HttpResponse;
  public class GrantCredit {
      public static void main(String[] args) throws Exception {
          String caseToken = "<case_token>";
          HttpClient client = HttpClient.newHttpClient();

          String jsonBody = """
              {
                  "action_type": "GRANT_PROVISIONAL_CREDIT",
                  "created_by": "Your Name"
              }
              """;
  HttpRequest request = HttpRequest.newBuilder()
              .uri(URI.create("https://your-subdomain.marqeta.com/v3/cases/" + caseToken + "/actions"))
              .header("X-Marqeta-Program-Short-Code", "your-program-code")
              .header("Authorization", "Basic YOUR_BASE64_ENCODED_STRING")
              .header("Content-Type", "application/json")
              .POST(BodyPublishers.ofString(jsonBody))
              .build();
          HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
          System.out.println("Response: " + response.body());
      }
  }
  ```
</CodeGroup>

## Simulating merchant representment

In some cases, the acquiring bank might forward the dispute claim to the merchant. A merchant can choose to accept the dispute or challenge it. Marqeta might request additional documentation from the cardholder to resubmit the dispute.

After the representment is received from the merchant, card network reviews the information to determine if the cardholder or merchant wins the dispute.

In the sandbox, you can simulate merchant representment (the merchant's response to the dispute) using the `POST /cases/<case_token>/disputetransitions` endpoint. Define the `amount` field within the `network_details.representment_details` object in the request body to simulate the representment.

### Sample request body

<Accordion title="Sample request" defaultOpen>
  <CodeGroup>
    ```bash Curl theme={null}
        curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/disputetransitions" \
            -H "X-Marqeta-Program-Short-Code: your-program-code" \
            -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
            -H "Content-Type: application/json" \
            -d '{
                "action": "REPRESENTMENT_RECEIVED",
                "created_by": "Your Name",
                "network_details": {
                    "representment_details": {
                        "amount": 10
                    }
                }
            }'
    ```

    ```javascript JavaScript theme={null}
        const moveToRepresentment = async (caseToken) => {
            const url = `https://your-subdomain.marqeta.com/v3/cases/${caseToken}/disputetransitions`;

            const payload = {
                action: "REPRESENTMENT_RECEIVED",
                created_by: "Your Name",
                network_details: {
                    representment_details: {
                        amount: 10
                    }
                }
            };

            const response = await fetch(url, {
                method: 'POST',
                headers: {
                    'X-Marqeta-Program-Short-Code': 'your-program-code',
                    'Authorization': 'Basic YOUR_BASE64_ENCODED_STRING',
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
            });

            const data = await response.json();
            console.log('Representment Logged:', data);
        };
    ```

    ```python Python theme={null}
        import requests
        case_token = "<case_token>"
        url = f"https://your-subdomain.marqeta.com/v3/cases/{case_token}/disputetransitions"

        headers = {
            "X-Marqeta-Program-Short-Code": "your-program-code",
            "Authorization": "Basic YOUR_BASE64_ENCODED_STRING",
            "Content-Type": "application/json"
        }

        payload = {
            "action": "REPRESENTMENT_RECEIVED",
            "created_by": "Your Name",
            "network_details": {
                "representment_details": {
                    "amount": 10
                }
            }
        }

        response = requests.post(url, headers=headers, json=payload)
        print(response.json())
    ```

    ```java Java theme={null}
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

        public class MoveToRepresentment {
            public static void main(String[] args) throws Exception {
                String caseToken = "<case_token>";
                HttpClient client = HttpClient.newHttpClient();

                String jsonBody = """
                    {
                        "action": "REPRESENTMENT_RECEIVED",
                        "created_by": "Your Name",
                        "network_details": {
                            "representment_details": {
                                "amount": 10
                            }
                        }
                    }
                    """;

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://your-subdomain.marqeta.com/v3/cases/" + caseToken + "/disputetransitions"))
                    .header("X-Marqeta-Program-Short-Code", "your-program-code")
                    .header("Authorization", "Basic YOUR_BASE64_ENCODED_STRING")
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                    .build();
                HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
                System.out.println("Status Code: " + response.statusCode());
                System.out.println("Response: " + response.body());
            }
        }
    ```
  </CodeGroup>
</Accordion>

### Sample response body

<Accordion title="Sample response" defaultOpen>
  <CodeGroup>
    ```json JSON theme={null}
    {
        "token": "50802d43-ffea-4280-8d01-41d8908a38a6",
        "created_time": "2026-03-10T13:59:07Z",
        "last_modified_time": "2026-03-10T13:59:07Z",
        "case_token": "<case_token>",
        "action": "REPRESENTMENT_RECEIVED",
        "created_by": "Your Name",
        "network_details": {
            "representment_details": {
            "amount": 10
            }
        }
    }
    ```
  </CodeGroup>
</Accordion>

This request transitions the network state to `representment` and Marqeta state remains as `CHARGEBACK_INITIATED`. If the merchant challenges the chargeback, you receive an `authorization.clearing.representment` event.

### Representment in Visa

When a dispute goes through the Visa network, the representment state does not always apply.

Visa uses the following dispute flows depending on the reason code provided:

* **Collaboration**: For reason codes related to fraud and authorization. This flow can simplify the case management process and move it along faster.
  * **Collaboration flow**: Initiated → Representment → Prearbitration (decline or responded) → Arbitration.
* **Allocation**: For all other reason codes. The allocation flow skips the representment portion and moves directly into pre-arbitration. State transitions for each flow is as described:
  * **Allocation flow**: Initiated → Prearbitration (decline or responded) → Arbitration.

### Simulating prearbitration

If Marqeta chooses to challenge the merchant's representment, it moves the dispute to the `prearbitration` network state, which allows the involved parties to provide further evidence. You can simulate this transition into prearbitration.

You can simulate the pre-arbitration action by the acquirer by passing `RESPOND_WITH_PREARB` in the `action` field.

### Sample request body

<Accordion title="Sample request" defaultOpen>
  <CodeGroup>
    ```bash Curl theme={null}
        curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/disputetransitions" \
            -H "X-Marqeta-Program-Short-Code: your-program-code" \
            -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
            -H "Content-Type: application/json" \
            -d '{
                "action": "RESPOND_WITH_PREARB",
                "created_by": "Your Name",
                "network_details": {
                    "prearbitration_details": {
                        "amount": 10
                    }
                }
            }'
    ```

    ```javascript JavaScript theme={null}
        const respondWithPreArb = async (caseToken) => {
            const url = `https://your-subdomain.marqeta.com/v3/cases/${caseToken}/disputetransitions`;

            const payload = {
                action: "RESPOND_WITH_PREARB",
                created_by: "Your Name",
                network_details: {
                    prearbitration_details: {
                        amount: 10
                    }
                }
            };

            const response = await fetch(url, {
                method: 'POST',
                headers: {
                    'X-Marqeta-Program-Short-Code': 'your-program-code',
                    'Authorization': 'Basic YOUR_BASE64_ENCODED_STRING',
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify(payload)
            });

            const data = await response.json();
            console.log('Pre-Arbitration Initiated:', data);
        };
    ```

    ```python Python theme={null}
        import requests

        case_token = "<case_token>"
        url = f"https://your-subdomain.marqeta.com/v3/cases/{case_token}/disputetransitions"

        headers = {
            "X-Marqeta-Program-Short-Code": "your-program-code",
            "Authorization": "Basic YOUR_BASE64_ENCODED_STRING",
            "Content-Type": "application/json"
        }

        payload = {
            "action": "RESPOND_WITH_PREARB",
            "created_by": "Your Name",
            "network_details": {
                "prearbitration_details": {
                    "amount": 10
                }
            }
        }

        response = requests.post(url, headers=headers, json=payload)
        print(response.json())
    ```

    ```java Java theme={null}
        import java.net.URI;
        import java.net.http.HttpClient;
        import java.net.http.HttpRequest;
        import java.net.http.HttpResponse;

    public class InitiatePreArb {
            public static void main(String[] args) throws Exception {
                String caseToken = "<case_token>";
                HttpClient client = HttpClient.newHttpClient();

                String jsonBody = """
                    {
                        "action": "RESPOND_WITH_PREARB",
                        "created_by": "Your Name",
                        "network_details": {
                            "prearbitration_details": {
                                "amount": 10
                            }
                        }
                    }
                    """;

                HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create("https://your-subdomain.marqeta.com/v3/cases/" + caseToken + "/disputetransitions"))
                    .header("X-Marqeta-Program-Short-Code", "your-program-code")
                    .header("Authorization", "Basic YOUR_BASE64_ENCODED_STRING")
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(jsonBody))
                    .build();

                HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
                System.out.println("Response Code: " + response.statusCode());
                System.out.println("Response Body: " + response.body());
            }
        }
    ```
  </CodeGroup>
</Accordion>

### Sample response body

<Accordion title="Sample response" defaultOpen>
  <CodeGroup>
    ```json JSON theme={null}
    {
        "token": "38cf59c9-132b-4655-9cb4-ffc5493624fc",
        "created_time": "2026-03-10T15:22:10Z",
        "last_modified_time": "2026-03-10T15:22:10Z",
        "case_token": "<case_token>",
        "action": "RESPOND_WITH_PREARB",
        "created_by": "Frank Disputes",
        "network_details": {
            "prearbitration_details": {
                "amount": 10
            }
        }
    }
    ```
  </CodeGroup>
</Accordion>

This request transitions the network state to `prearbitration` and Marqeta state remains as `CHARGEBACK_INITIATED`.

Marqeta sends you the `chargebacktransitions.prearbitration` webhook.

## Responding to prearbitration

At this point, the merchant can submit further evidence for the case. The specific requirements for the `prearbitration_response_details` object differ across the various card networks.

You can simulate the reponse to pre-arbitration action to the acquirer by passing `RESPOND_WITH_PREARB_RESPONSE` in the `action` field.

This example follows the Mastercard object, which requires only a list of associated document UUIDs in the `attached_contents` field in the `network_details.prearbitration_response_details` object.

<Warning>
  **Caution**<br />For testing purposes, pass an empty list in `attached_contents`. You can upload new documents and pass those UUIDs in the list.
</Warning>

### Sample request body

<Accordion title="Sample request" defaultOpen>
  <CodeGroup>
    ```bash Curl theme={null}
        curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/disputetransitions" \
            -H "X-Marqeta-Program-Short-Code: your-program-code" \
            -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
            -H "Content-Type: application/json" \
            -d '{
                "action": "RESPOND_WITH_PREARB_RESPONSE",
                "created_by": "Your Name",
                "network_details": {
                    "prearbitration_response_details": {
                        "attached_contents": []
                    }
                }
            }'
    ```

    ```javascript JavaScript theme={null}
    ```
  </CodeGroup>

  <Accordion defaultOpen>
    <CodeGroup>
      ```javascript JavaScript theme={null}
      ```

      ```python Python theme={null}
      ```

      ```java Java theme={null}
      ```
    </CodeGroup>
  </Accordion>

  ### Sample response body

  <Accordion title="Sample response" defaultOpen>
    <CodeGroup>
      ```json JSON theme={null}
      {
          "token": "20d26d96-7df8-4280-87ba-4f319616211a",
          "created_time": "2026-03-10T15:40:26Z",
          "last_modified_time": "2026-03-10T15:40:26Z",
          "case_token": "<case_token>",
          "action": "RESPOND_WITH_PREARB_RESPONSE",
          "created_by": "Frank Disputes",
          "network_details": {
              "prearbitration_response_details": {
                  "attached_contents": []
              }
          }
      }
      ```
    </CodeGroup>
  </Accordion>

  The network state remains as `prearbitration` and Marqeta state remains as `CHARGEBACK_INITIATED`. The `chargebacktransitions.prearbitration.responded` webhook event sent.

  ## Moving to arbitration

  Assume that the acquirer (merchant) does not agree with the pre-arbitration process. You can simulate an arbitration request to proceed by passing `RESPOND_WITH_ARB` in the `action` field.

  At this point, Marqeta transitions the dispute to the card network, who will provide the final and indisputable decision on the case.

  ### Sample request body

  <Accordion title="Sample request" defaultOpen>
    <CodeGroup>
      ```bash Curl theme={null}
          curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/disputetransitions" \
              -H "X-Marqeta-Program-Short-Code: your-program-code" \
              -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
              -H "Content-Type: application/json" \
              -d '{
                  "action": "RESPOND_WITH_ARB",
                  "created_by": "Your Name"
              }'
      ```

      ```javascript JavaScript theme={null}
      ```

      ```python Python theme={null}
      ```

      ```java Java theme={null}
      ```
    </CodeGroup>
  </Accordion>
</Accordion>

### Sample response body

<Accordion title="Sample response" defaultOpen>
  <CodeGroup>
    ```json JSON theme={null}
    {
        "token": "5b4a894f-8bc7-41b9-87bd-4ebe3225fd3e",
        "created_time": "2026-03-10T15:53:24Z",
        "last_modified_time": "2026-03-10T15:53:24Z",
        "case_token": "<case_token>",
        "action": "RESPOND_WITH_ARB",
        "created_by": "Your Name"
    }
    ```
  </CodeGroup>
</Accordion>

The network state remains as `arbitration` and the Marqeta state remains as `CHARGEBACK_INITIATED`. Marqeta sends you the `chargebacktransitions.arbitration` webhook.


## Related topics

- [Disputes in the Marqeta Dashboard](/docs/developer-guides/disputes-dashboard.md)
- [Managing Visa Disputes](/docs/developer-guides/managing-visa-disputes.md)
- [About Disputes](/docs/developer-guides/about-disputes.md)
- [About Regulation E](/docs/developer-guides/disputes-regulation-e.md)
- [Lifecycle of a Dispute](/docs/lifecycle-of-a-dispute-dispute-lifecycle.md)