Skip to main content
When a cardholder reports a problem with a transaction such as unauthorized use, merchandise that never arrived, or a billing error, you can open a dispute on their behalf using the POST /cases endpoint. Marqeta routes the dispute to the appropriate card network and initiates the chargeback process.
The POST /cases endpoint supports two types of submissions: chargeback requests, which initiate the formal dispute and recovery process, and fraud reports, which record fraud for card network reporting purposes but do not initiate chargeback recovery.
The structure of your request payload depends on the following:
  • Card network — Visa, Mastercard, and PULSE each have different payload requirements.
  • Dispute category — Such as Fraud, Consumer, Authorization, or Processing Error.
  • Reason code — The specific reason for the dispute within that category.
Marqeta provides a response that indicates that the dispute has been created successfully or provides an error message if unsuccessful.

​
Prerequisites

Before creating a dispute, make sure you have the following:
  • Authentication — A valid API key or access token to authenticate your request.
  • original_transaction_token — The token of the transaction being disputed. You can retrieve this using the Transactions API.
  • Card network — The network associated with the original transaction (Visa, Mastercard, or PULSE).
  • Dispute reason — The dispute reason that applies to the cardholder’s situation. See the payload reference below for the full list of supported reason codes by network.

​
Payload examples

This section provides payload examples to create disputes. These examples are based on scenarios with various combinations of card networks, disputes categories, and reason codes.

​
Walkthrough

This section walks through the following common dispute scenarios end to end:
  • a Visa consumer dispute
  • a Mastercard dispute
  • a Visa fraud report
  • a PULSE consumer dispute.

​
Example 1: Visa — Merchandise not received

Scenario: A cardholder purchased a jacket online but never received it. They contacted the merchant with no resolution. Step 1: Identify your parameters
  • Network: Visa
  • Category: Consumer
  • Reason code: SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED
Step 2: Construct the payload
Step 3: Send the request
In the following example, replace the <payload above> text in the last line with the JSON payload from Step 2.
Step 4: Review the response A successful request returns a 201 Created response with a case object. The key fields to note:
  • token — Your unique case identifier. Save this for future status checks.
  • dispute_state — The current state of the dispute in the card network workflow.
  • provisional_credit_granted — Whether a provisional credit has been applied to the cardholder’s account.

​
Example 2: Mastercard — Cancelled recurring transaction

Scenario: A cardholder was billed for a recurring subscription they cancelled two months ago. Step 1: Identify your parameters
  • Network: Mastercard
  • Reason code: CANCELLED_RECURRING_TRANSACTION
Mastercard payloads generally require the core dispute fields and a network_comment explaining the dispute context. For fraud reports, additional fields are required — see the Fraud Report tab under the Mastercard section for details.
Step 2: Construct the payload
Step 3: Send the request
In the following example, replace the <payload above> text in the last line with the JSON payload from Step 2.
Step 4: Review the response A successful request returns a 201 Created response with a case object. The key fields to note:
  • token — The unique case identifier. Save this for future status checks.
  • dispute_state — The current state of the dispute in the card network workflow.
  • network_case_number - Assigned by Mastercard when the case enters their system.
  • provisional_credit_granted — Whether a provisional credit has been applied to the cardholder’s account.

​
Example 3: Visa — Fraud report

Scenario: A cardholder reports that a fraudulent application for credit was submitted in the account holder’s name. Step 1: Identify your parameters
  • Network: Visa
  • Category: Fraud Report
  • Reason code: FRAUD_REPORT
  • Fraud type: FRAUDULENT_APPLICATION
Fraud reports record fraud for card network reporting but do not initiate chargeback recovery. If you want to recover funds, use a fraud-category dispute reason code instead.
Step 2: Construct the payload The following is an example of a fraud report request to the Visa card network for a fraudulent application.
In the following example, replace the text of the memo with details relevant to the fraud report.
Step 3: Send the request
In the following example, replace the <payload above> text in the last line with the JSON payload from Step 2.
Step 4: Review the response A successful request returns a 201 Created response with a case object. For fraud reports, note the following key fields:
  • token — The unique case identifier. Save this for future status checks.
  • dispute_state — The current state of the fraud report in the card network workflow.
  • provisional_credit_granted — For fraud reports, this value will always be false, as no chargeback recovery is initiated.
The following case object is an example of a response sent by the Visa network that related to the payload for the fraud report shown above.

​
Example 4: PULSE — Service not provided

Scenario: A cardholder paid for a home cleaning service that was never performed. They contacted the merchant with no resolution. Step 1: Identify your parameters
  • Network: PULSE
  • Category: Consumer
  • Reason code: SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED
Step 2: Construct the payload
Step 3: Send the request
In the following example, replace the <payload above> text in the last line with the JSON payload from Step 2.
Step 4: Review the response A successful request returns a 201 Created response with a case object. The key fields to note:
  • token — The unique case identifier. Save this for future status checks.
  • dispute_state — The current state of the dispute in the PULSE card network workflow.
See the following example case object.

​
Understanding the response

The response schema is the same regardless of card network or reason code, but not all fields will be populated in every response. The fields most relevant to your workflow are:

​
Next steps

After creating a dispute, you can:
  • Check dispute status — Retrieve the case using GET /cases/{token} to monitor its progress through the card network workflow.
  • Update a dispute — Use PUT /cases/{token} to add information or documentation to an open case.
  • Handle card network responses — If network_failure_response is populated, review the error and resubmit with corrected fields.

​
Error handling

If your request is rejected by the card network, the response includes a network_failure_response field describing the reason for the rejection. Review the value of this field, correct the relevant parameters in your payload, and resubmit the request.

​
Payload reference

Use the tabs below to find the correct payload for your card network and dispute reason code. For Visa and PULSE payloads with conditional fields, a dependency diagram is provided alongside the flat payload example.

​
How to read the dependency diagrams

For Visa and PULSE payloads with conditional fields, a dependency diagram is provided alongside the flat payload example. These diagrams show which fields are conditionally required based on the values of other fields. Here is how to read them:
  • Branches — A [BRANCH: VALUE] label means the fields below it are only applicable when the parent field is set to that value.
  • IF conditions — An IF: True or IF: False label means the fields below it are only required when the parent boolean resolves to that value.
  • Optional fields — Fields marked [Optional] are not required to submit the dispute but may be relevant to your case.
Use the flat payload as your starting point, then use the dependency diagram to remove fields that don’t apply to your specific scenario.
Visa dispute payloads include conditional fields that vary by dispute category and reason code. All detail fields must be sent flattened in the request body, regardless of their interdependencies. Flattened means that all fields are included at the same level within their parent object — no conditional nesting based on the values of sibling fields. This section covers five dispute categories — Fraud, Processing Errors, Consumer, Fraud Report, and Authorization — each with flat payload examples and dependency diagrams where applicable.
Fraud disputes cover unauthorized transactions and Europay, Mastercard, and Visa (EMV) liability shift scenarios. Use the reason codes in this category when a cardholder reports a transaction they did not authorize.

​
EMV_LIABILITY_SHIFT_COUNTERFEIT_FRAUD

Cannot be used for Chip-initiated or fallback transactions.

​
EMV_LIABILITY_SHIFT_NON_COUNTERFEIT_FRAUD

Can only be used when the card has CVM hierarchy where PIN is preferred over signature.

​
NOT_AUTHORIZED_CARD_PRESENT

Condition: Card-present environment.

​
NOT_AUTHORIZED_CARD_ABSENT