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.

This guide uses a minimal configuration Mastercard cleared transaction as an example.

Prerequisites

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

A cleared transaction
A webhook handler

For more information about setting up a webhook handler, see Set Up a Webhook Handler.

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

Create a dispute

To create a dispute, you must open a case, upload supporting documents, and transition it to the READY state. For more information on creating a dispute, see Creating a Dispute.

Opening the dispute case

To open a dispute case, send a POST /cases request with the following fields:

original_transaction_token: The clearing transaction token.
dispute_amount: The amount in dispute.
dispute_reason: A reason code (for example, NOT_AUTHORIZED_CARD_ABSENT for fraud, or CARDHOLDER_DISPUTE for goods not received).

The request payload for dispute creation differs depending on the network and dispute reason. The following sample request for a Mastercard cleared transaction is an example of a minimal configuration.
The cardholder_contact_date parameter is required for REG_E disputes, but it is not required for this example with minimal configuration.
The dispute_reason enum is different from reason_code on a transition which is a network-side identifier.

Sample request body

Sample request

    curl --request POST \
    --url https://your-subdomain.marqeta.com/v3/cases \
    --header 'Content-Type: application/json' \
    --data '
    {
        "type": "LEGACY_DISPUTE",
        "dispute_details": {
            "original_transaction_token": "019ca0e2-a9e3-7f30-b120-957e44eb3408",
            "dispute_amount": 10,
            "dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT",
            "cardholder_contact_date": "2023-07-18T22:24:46.251Z"
        },
        "memo": "A test legacy dispute case"
    }
    '

Sample response body

Sample response

{
    "original_transaction_token": "019ca0e2-a9e3-7f30-b120-957e44eb3408",
    "original_transaction_type": "authorization.clearing",
    "dispute_amount": 10.00,
    "currency_code": "USD",
    "dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT",
    "network": "MASTERCARD",
    "network_case_number": "",
    "card_token": "e25551b1-f47a-4310-a563-1a02cd09e0f7",
    "provisional_credit_granted": false,
    "acquirer_fee": 0.0000,
    "associated_transaction_selection_required": false
}

Upon creation, the dispute case is assigned the OPEN or OPEN_WITH_ACTION_REQUIRED Marqeta state.

Uploading supporting documents

To upload supporting documents to defend the dispute claim, use POST /cases/{token}/contents. You must upload supporting documents while the case is still in OPEN, OPEN_WITH_ACTION_REQUIRED, or READY states. Once a dispute is submitted to the card network, you can no longer attach documents. For this example in particular, Mastercard requires supporting documents for all dispute claims.

Sample request body

You can upload supporting document file to the disputes API as a binary in an application/json in the Content-Type field, or as part of a multipart/form-data. Examples for both modes follow below.

Sample binary in body request

    curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/contents" \
        -H "X-Marqeta-Program-Short-Code: your-program-code" \
        -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
        -H "Content-Type: application/json" \
        -H "Cache-Control: no-cache" \
        -d '{
            "document_category": "RECEIPT",
            "document_name": "receipt_2.pdf",
            "document_data": "<file_binary_code>"
        }'

Sample multipart form request

    curl -X POST "https://your-subdomain.marqeta.com/v3/cases/<case_token>/contents" \
        -H "X-Marqeta-Program-Short-Code: your-program-code" \
        -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
        -H "Cache-Control: no-cache" \
        -F 'body={
        "document_category": "AUTHORIZATION_RECORD",
        "document_name": "authorization_record.pdf"
        };type=application/json' \
        -F "file=@/path/to/your-file ;type=application/pdf"

Sample response body

Sample response

{
    "created_time": "2026-03-09T14:03:52Z",
    "last_modified_time": "2026-03-09T14:03:52Z",
    "token": "6fab0fc2-fef6-4949-be2b-d0d8175fba82",
    "document_category": "AUTHORIZATION_RECORD",
    "document_name": "receipt.pdf",
    "case_token": "<case_token>",
    "document_content_type": "application/pdf",
    "network_process_type": "SUBMITTED",
    "network_process_time": "2026-03-09T14:03:53Z"
}

The Marqeta state remains as OPEN or OPEN_WITH_ACTION_REQUIRED.

Verifying the document upload

You can verify that your document was uploaded correctly by sending a request to the GET /cases/{token}/contents endpoint. The response body includes only the list of uploaded documents. However, if you want to download these files, include download_link=true as a query parameter to receive the link in the response body.

Sample request body

curl -X GET "https://your-subdomain.marqeta.com/v3/cases/<case_token>/contents/<document_token>?download_link=true" \
    -H "X-Marqeta-Program-Short-Code: your-program-code" \
    -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
    -H "Content-Type: application/json" \
    -H "Cache-Control: no-cache"

Transitioning a dispute case

After you provide all the required case information and upload supporting documents, transition the case to the READY state by performing the REVIEW action. Use POST /cases/{token}/transitions and set the action field value to REVIEW.

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": "REVIEW",
            "reason_code": "05",
            "created_by": "Your Name"
        }'

Sample response body

Sample response

{
    "case_token": "<case_token>",
    "token": "b70e779c-4c3a-48bf-861e-10486da57db8",
    "reason_code": "05",
    "reason_description": "Under Review",
    "created_by": "Your Name",
    "from_state": "OPEN",
    "state": "READY",
    "action": "REVIEW",
    "created_date": "2026-03-09T19:04:30Z"
}

The case transitions to READY, and it is now eligible for submission to the card network.

Withdrawing a dispute voluntarily

You can withdraw a dispute while it is in the OPEN, OPEN_WITH_ACTION_REQUIRED, or READY state by sending a request to the POST /cases/<case_token>/transitions endpoint. This moves the case to a CLOSED state.

You will not be allowed to withdraw disputes once they have been submitted to the card network and assigned the CHARGEBACK_INITIATED state.

Sample request body

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": "WITHDRAW_AND_CLOSE",
    "reason_code": "40",
    "created_by": "Your Name"
}'

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.

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

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.

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.

There may 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.

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

Simulating Merchant representment

In some cases, the acquiring bank may forward the dispute claim to the merchant. A merchant may 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
                }
            }
        }'

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

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.

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.

Closing the case and notifying the cardholder

At this stage, the network has decided whether the case is won or lost. In production, you must notify the cardholder of the outcome. To simulate this transition, use one of the following actions:

CLOSE_WITH_CASE_WON
CLOSE_WITH_NETWORK_REJECTED

The example below demonstrates a case.won flow by sending CLOSE_WITH_CASE_WON 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": "CLOSE_WITH_CASE_WON",
            "created_by": "Your Name"
        }'

Sample response body

Sample response

{
    "token": "203a8a7d-944f-40a4-a160-25da40573f41",
    "created_time": "2026-03-10T16:02:10Z",
    "last_modified_time": "2026-03-10T16:02:10Z",
    "case_token": "<case_token>",
    "action": "CLOSE_WITH_CASE_WON",
    "created_by": "Frank Disputes"
}

Marqeta states transitions to CLOSED regardless of the decision and the network state transitions to case.won or case.lost automatically, based on this decision.

Confirming the dispute status

Marqeta state for dispute is now CLOSED. You can check the state of your Dispute with the following request.

Sample request body

Sample request

    curl -X GET "https://your-subdomain.marqeta.com/v3/cases/<case_token>" \
        -H "X-Marqeta-Program-Short-Code: your-program-code" \
        -H "Authorization: Basic YOUR_BASE64_ENCODED_STRING" \
        -H "Content-Type: application/json"

Next steps

After successfully navigating a basic dispute lifecycle, you can now begin tailoring your code to your specific use cases. The payloads, responses, and actions you implement will vary significantly depending on the card networks and the regulations your program is subject to.

​Prerequisites

​Dispute state flow

​Create a dispute

​Opening the dispute case

​Sample request body

​Sample response body

​Uploading supporting documents

​Sample request body

​Sample response body

​Verifying the document upload

​Sample request body

​Transitioning a dispute case

​Sample request body

​Sample response body

​Withdrawing a dispute voluntarily

​Sample request body

​Submit a dispute

​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

​Closing the case and notifying the cardholder

​Sample request body

​Sample response body

​Confirming the dispute status

​Sample request body

​Next steps

Prerequisites

Dispute state flow

Create a dispute

Opening the dispute case

Sample request body

Sample response body

Uploading supporting documents

Sample request body

Sample response body

Verifying the document upload

Sample request body

Transitioning a dispute case

Sample request body

Sample response body

Withdrawing a dispute voluntarily

Sample request body

Submit a dispute

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

Closing the case and notifying the cardholder

Sample request body

Sample response body

Confirming the dispute status

Sample request body

Next steps