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.

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

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

Sample request

    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"
        }'

    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);
    };

    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())

    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());
        }
    }

Sample response body

Sample response

{
    "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"
}

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

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

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
There can be a delay between the time an action is taken and when the webhook is sent. This is true for all webhooks.

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

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.

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

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"
}'

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);
};

    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())

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());
    }
}

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

Sample request

    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
                }
            }
        }'

    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);
    };

    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())

    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());
        }
    }

Sample response body

Sample response

{
    "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
        }
    }
}

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

Sample request

    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
                }
            }
        }'

    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);
    };

    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())

    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());
        }
    }

Sample response body

Sample response

{
    "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
        }
    }
}

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.

Caution
For testing purposes, pass an empty list in attached_contents. You can upload new documents and pass those UUIDs in the list.

Sample request body

Sample request

    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": []
                }
            }
        }'

Sample response body

Sample response

{
    "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": []
        }
    }
}

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

Sample request

    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"
        }'

Sample response body

Sample response

{
    "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"
}

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

Platform Overview

Program Administration

Card Issuing

Card Processing

Data & Reporting

Accounts & Money Movement

Risk, Fraud, & Disputes

Cardholder User Experience

Marqeta in Europe

Submitting a dispute to the card network

Sample request body

Sample response body

Dispute identifiers

Recommended actions

Providing provisional credit

Sample request body

Simulating merchant representment

Sample request body

Sample response body

Representment in Visa

Simulating prearbitration

Sample request body

Sample response body

Responding to prearbitration

Sample request body

Sample response body

Moving to arbitration

Sample request body

Sample response body

​Submitting a dispute to the card network

​Sample request body

​Sample response body

​Dispute identifiers

​Recommended actions

​Providing provisional credit

​Sample request body

​Simulating merchant representment

​Sample request body

​Sample response body

​Representment in Visa

​Simulating prearbitration

​Sample request body

​Sample response body

​Responding to prearbitration

​Sample request body

​Sample response body

​Moving to arbitration

​Sample request body

​Sample response body

Submitting a dispute to the card network

Sample request body

Sample response body

Dispute identifiers

Recommended actions

Providing provisional credit

Sample request body

Simulating merchant representment

Sample request body

Sample response body

Representment in Visa

Simulating prearbitration

Sample request body

Sample response body

Responding to prearbitration

Sample request body

Sample response body

Moving to arbitration

Sample request body

Sample response body