> ## 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.
# Creating a Dispute
> Create disputes on behalf of cardholders using the POST /cases endpoint, with step-by-step examples for Visa, Mastercard, and PULSE.
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](/core-api/transactions).
* **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](#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**
```json theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder reports merchandise never received after contacting merchant",
"dispute_details": {
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"dispute_amount": 89.99,
"cardholder_contact_date": "2026-03-10T09:00:00Z",
"original_transaction_token": "a2d7d73a-02c6-4865-9fa6-6c998a179b2a",
"consumer_dispute_type_dispute_details": {
"service_not_provided_merchandise_not_received_details": {
"detailed_description_of_what_was_purchased_and_explanation_of_the_dispute": "Cardholder ordered a blue denim jacket (size M) on February 20, 2025\. Expected delivery was March 5, 2025\. Item was never received and merchant has not responded to two contact attempts.",
"expected_receipt_date": "2026-03-05T00:00:00Z",
"merchandise_or_services": "MERCHANDISE",
"did_cardholder_attempt_to_resolve_dispute_with_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": false,
"did_cardholder_return_merchandise": false,
"did_cardholder_attempt_to_return_merchandise": false,
"is_merchant_in_bankruptcy_liquidation": false,
"third_party_gift_card_indicator": false,
"merchandise_delivered_late": false,
"was_merchandise_delivered_to_wrong_location": false,
"did_merchant_cancel_merchandise": false
}
}
}
}
```
**Step 3: Send the request**
In the following example, replace the `` text in the last line with the JSON payload from Step 2.
```bash theme={null}
curl \--request POST \
\--url https://sandbox-api.marqeta.com/v3/cases \
\--header 'Authorization: Basic ' \
\--header 'Content-Type: application/json' \
\--data ''
```
**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**
```json theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder cancelled subscription in January; merchant continued billing in February and March.",
"network_comment": "Cardholder cancelled their monthly streaming subscription on January 15, 2025 via the merchant's online portal and received a confirmation email. Despite cancellation, the merchant charged the cardholder $14.99 on February 1 and March 1, 2025.",
"dispute_details": {
"original_transaction_token": "75a1d6d5-01f8-4c9a-b89d-ecf80658e801",
"dispute_amount": 14.99,
"dispute_reason": "CANCELLED_RECURRING_TRANSACTION",
"cardholder_contact_date": "2026-03-05T14:00:00Z"
}
}
```
**Step 3: Send the request**
In the following example, replace the `` text in the last line with the JSON payload from Step 2.
```bash theme={null}
curl \--request POST \
\--url https://sandbox-api.marqeta.com/v3/cases \
\--header 'Authorization: Basic ' \
\--header 'Content-Type: application/json' \
\--data ''
```
**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.
```json theme={null}
{
"dispute_details": {
"dispute_reason": "FRAUD_REPORT",
"dispute_amount": 50,
"fraud_category_type_dispute_details": {
"fraud_type": "FRAUDULENT_APPLICATION"
},
"original_transaction_token": "1c0a45c3-8212-4524-b679-610cf4d231a8",
"cardholder_contact_date": "2026-03-12T11:30:00Z"
},
"memo": "This is a QE test",
"type": "DISPUTE"
}
```
**Step 3: Send the request**
In the following example, replace the `` text in the last line with the JSON payload from Step 2.
```bash theme={null}
curl \--request POST \
\--url https://sandbox-api.marqeta.com/v3/cases \
\--header 'Authorization: Basic ' \
\--header 'Content-Type: application/json' \
\--data ''
```
**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.
```json theme={null}
{
"created_time": "2025-10-10T14:13:49Z",
"last_modified_time": "2025-10-10T14:13:49Z",
"token": "qa01-2054",
"type": "DISPUTE",
"memo": "This is a QE test",
"program_short_code": "qa01",
"user_token": "2ccc806a-d9a4-4357-aa2b-897ec86c409f",
"state": "CLOSED",
"dispute_details": {
"original_transaction_token": "1c0a45c3-8212-4524-b679-610cf4d231a8",
"original_transaction_type": "authorization.clearing",
"dispute_amount": 50.00,
"currency_code": "USD",
"dispute_reason": "FRAUD_REPORT",
"network": "Visa",
"network_case_number": "5155784824",
"card_token": "8db8321d-56f5-42b4-a9c3-f7d3a64bc92a",
"provisional_credit_granted": false,
"acquirer_fee": 0.0000,
"associated_transaction_selection_required": true
}
}
```
### 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**
```json theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder paid for home cleaning service that was never performed.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 120.00,
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"cardholder_contact_date": "2026-05-10T09:00:00Z",
"consumer_dispute_type_dispute_details": {
"service_not_provided_merchandise_not_received_details": {
"agreed_delivery_date_or_service_date": "2026-05-01T00:00:00Z",
"cash_over_indicator": "M"
}
}
}
}
```
**Step 3: Send the request**
In the following example, replace the `` text in the last line with the JSON payload from Step 2.
```bash theme={null}
curl \--request POST \
\--url https://sandbox-api.marqeta.com/v3/cases \
\--header 'Authorization: Basic ' \
\--header 'Content-Type: application/json' \
\--data ''
```
**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.
```json theme={null}
{
"token": "case-123",
"type": "DISPUTE",
"state": "OPEN",
"memo": "Cardholder paid for home cleaning service that was never performed.",
"user_token": "usr_8b2c4d1e-9f3a-4b6c-8d2e-1f4a7b9c0e5d",
"created_time": "2026-05-12T14:23:11.000Z",
"last_modified_time": "2026-05-12T14:23:11.000Z",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"original_transaction_type": "authorization.clearing",
"dispute_amount": 120.00,
"currency_code": "USD",
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"dispute_reason_code": "4555",
"network": "PULSE",
"card_token": "crd_5e2f1a9b-3c7d-4e8f-a1b2-6d4e9f0c3a7b",
"cardholder_contact_date": "2026-05-10T09:00:00Z",
"provisional_credit_granted": false,
"associated_transaction_selection_required": false,
"consumer_dispute_type_dispute_details": {
"service_not_provided_merchandise_not_received_details": {
"agreed_delivery_date_or_service_date": "2026-05-01T00:00:00Z",
"cash_over_indicator": "M"
}
}
},
"case_tags": []
}
```
## 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:
| Field | Description |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `token` | Unique identifier for this case. Use it to retrieve or update the case later. |
| `state` | The internal case state within Marqeta's system. |
| `dispute_state` | The state of the dispute within the card network's workflow. Possible values vary by card network. |
| `provisional_credit_granted` | Whether Marqeta has granted the cardholder a provisional credit while the dispute is in progress. |
| `network_case_number` | The case number assigned by the card network. Available once the case has been submitted to the card network. |
| `network_failure_response` | Populated if the card network rejected the submission. Use this to diagnose and correct the request. |
```json theme={null}
{
"token": "string",
"type": "DISPUTE",
"memo": "string",
"network_comment": "string",
"program_short_code": "string",
"user_token": "string",
"business_token": "string",
"state": "NONE",
"assignee": "string",
"zendesk_ticket_id": "string",
"type_change_time": "2026-03-12T11:30:00Z",
"created_time": "2026-03-12T11:30:00Z",
"last_modified_time": "2026-03-12T11:30:00Z",
"dispute_details": {
"original_transaction_token": "string",
"original_transaction_id": 1234567,
"original_transaction_type": "string",
"dispute_amount": 89.99,
"dispute_amount_change_reason": "MERCHANT_ISSUED_PARTIAL_REFUND",
"currency_code": "USD",
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"dispute_reason_code": "string",
"chargeback_token": "string",
"network": "Visa",
"network_case_number": "string",
"acquirer_fee": 0,
"associated_transaction_selection_required": true,
"network_failure_response": "string",
"card_token": "string",
"regulation_type": "REG_E",
"provisional_credit_granted": true,
"dispute_state": "RETRIEVAL_REQUEST",
"processing_error_type_dispute_details": {},
"consumer_dispute_type_dispute_details": {},
"network_case_status_details": {},
"additional_dispute_details": {},
"fraud_dispute_type_details": {},
"fraud_category_type_dispute_details": {},
"fraud_classification_type_dispute_details": {},
"regulation_details": {},
"partial_dispute_resolution": {},
"cardholder_contact_date": "2026-03-10T09:00:00Z",
"account_status": "string"
}
}
```
## 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.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"dispute_reason": "EMV_LIABILITY_SHIFT_COUNTERFEIT_FRAUD",
"dispute_amount": 100.01,
"original_transaction_token": "0802aaf5-ee33-4663-a34a-196fb9712797",
"cardholder_contact_date": "2026-05-01T01:00:00Z",
"fraud_dispute_type_details": {
"general_fraud_type_dispute_details": {
"chip_on_card": true
}
}
}
}
```
### EMV\_LIABILITY\_SHIFT\_NON\_COUNTERFEIT\_FRAUD
Can only be used when the card has CVM hierarchy where PIN is preferred over signature.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"dispute_reason": "EMV_LIABILITY_SHIFT_NON_COUNTERFEIT_FRAUD",
"dispute_amount": 100.01,
"original_transaction_token": "0802aaf5-ee33-4663-a34a-196fb9712797",
"cardholder_contact_date": "2026-05-01T01:00:00Z",
"fraud_dispute_type_details": {
"general_fraud_type_dispute_details": {
"chip_on_card": false
}
}
}
}
```
### NOT\_AUTHORIZED\_CARD\_PRESENT
Condition: Card-present environment.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"dispute_reason": "NOT_AUTHORIZED_CARD_PRESENT",
"dispute_amount": 100.01,
"original_transaction_token": "a2d7d73a-02c6-4865-9fa6-6c998a179b2a",
"cardholder_contact_date": "2026-05-01T01:00:00Z",
"fraud_dispute_type_details": {
"general_fraud_type_dispute_details": {
"chip_on_card": true
}
}
}
}
```
### NOT\_AUTHORIZED\_CARD\_ABSENT
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"original_transaction_token": "0bbf0259-bc8b-46f1-a2de-76135d5993eb",
"dispute_amount": 99.99,
"dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT",
"cardholder_contact_date": "2026-01-15T10:30:00Z",
"fraud_dispute_type_details": {
"general_fraud_type_dispute_details": {
"chip_on_card": false
}
}
}
}
```
Errors in the processing category will have the `dispute_details \-> processing_error_type_dispute_details` object defined.
Below are examples of specific payloads for dispute reasons in the Processing category.
### INCORRECT\_TRANSACTION\_AMOUNT
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder was charged $110.01 but receipt shows $95.00.",
"dispute_details": {
"dispute_reason": "INCORRECT_TRANSACTION_AMOUNT",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"dispute_amount_change_reason": "PARTIAL_DISPUTE",
"processing_error_type_dispute_details": {
"incorrect_transaction_amount_details": {
"what_is_the_amount_on_the_cardholders_receipt": 95.00,
"what_is_the_currency_on_the_cardholders_receipt": "USD",
"is_the_dispute_due_to_the_difference_between_quoted_price_and_actual_charges_made_by_the_merchant": true
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
### INCORRECT\_TRANSACTION\_CODE
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"original_transaction_token": "75a1d6d5-01f8-4c9a-b89d-ecf80658e801",
"dispute_amount": 150.00,
"dispute_reason": "INCORRECT_TRANSACTION_CODE",
"cardholder_contact_date": "2026-01-15T10:30:00Z"
}
}
```
### INCORRECT\_CURRENCY
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder was charged in USD but agreed to CAD.",
"dispute_details": {
"dispute_reason": "INCORRECT_CURRENCY",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"incorrect_currency_details": {
"incorrect_currency_reason": "CURRENCY_DIFFERENCE",
"what_was_the_correct_currency": 124
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
processing_error_type_dispute_details
└── incorrect_currency_details
|
├── incorrect_currency_reason (Enum: CURRENCY_DIFFERENCE | DCC_DISPUTE)
|
├── [BRANCH: CURRENCY_DIFFERENCE]
| └── what_was_the_correct_currency (Integer)
|
└── [BRANCH: DCC_DISPUTE]
└── certification_that_the_cardholder_did_not_agree_to_dynamic_currency_conversion_and_did_not_make_an_active_choice (Boolean)
```
### INCORRECT\_ACCOUNT\_NUMBER
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Transaction posted to incorrect account number.",
"dispute_details": {
"dispute_reason": "INCORRECT_ACCOUNT_NUMBER",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"incorrect_account_number_details": {
"is_the_account_number_on_the_issuers_master_file": true,
"does_the_account_number_on_the_receipt_match_the_cardholders_account_number_or_token": false
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
processing_error_type_dispute_details
|
└── incorrect_account_number_details
|
└── is_the_account_number_on_the_issuers_master_file (Boolean)
|
└── IF: True
└── does_the_account_number_on_the_receipt_match_the_cardholders_account_number_or_token (Boolean)
```
### DUPLICATE\_PROCESSING\_OR\_PAID\_BY\_OTHER\_MEANS
The payload differs depending on whether the dispute's error type is Duplicate or Paid By Other Means.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder was charged twice for the same transaction.",
"dispute_details": {
"dispute_reason": "DUPLICATE_PROCESSING_OR_PAID_BY_OTHER_MEANS",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"duplicate_processing_or_paid_by_other_means_details": {
"error_type": "DUPLICATE",
"both_transactions_in_same_account": true,
"other_transaction_reference_token": "75a1d6d5-01f8-4c9a-b89d-ecf80658e801",
"cardholder_attempted_to_resolve": true,
"is_attempt_to_resolve_prohibited_by_local_law": false
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
processing_error_type_dispute_details
|
└── duplicate_processing_or_paid_by_other_means_details
|
├── error_type (Enum: DUPLICATE | PAID_BY_OTHER_MEANS)
|
├── [BRANCH: DUPLICATE]
| └── both_transactions_in_same_account (Boolean)
| |
| ├── IF: True
| | └── other_transaction_reference_token (String)
| |
| └── IF: False
| └── transaction_in_different_visa_account (Boolean)
| |
| ├── IF: True
| | └── other_transaction_reference_token (String)
| |
| └── IF: False
| ├── is_other_transaction_with_same_merchant (Boolean) \- NOTE: Set it to True
| |
| ├── cardholder_attempted_to_resolve (Boolean)
| | └── IF: False
| | └── is_attempt_to_resolve_prohibited_by_local_law (Boolean)
| |
| └── provided_proof_of_other_means_type (Enum)
| ├── IF: THIRD_PARTY_VOUCHER
| | └── is_evidence_of_merchant_passed_funds_provided (Boolean)
| ├── IF: OTHER_TRANSACTION_ARN
| | └── other_visa_transaction_arn (String)
| └── IF: OTHER_TRANSACTION_INFORMATION
| └── other_visa_transaction_information (String)
|
└── [BRANCH: PAID_BY_OTHER_MEANS]
├── cardholder_attempted_to_resolve (Boolean)
| └── IF: False
| └── is_attempt_to_resolve_prohibited_by_local_law (Boolean)
|
└── both_transactions_in_same_account (Boolean)
|
├── IF: True
| └── other_transaction_reference_token (String)
|
└── IF: False
└── transaction_in_different_visa_account (Boolean)
|
├── IF: True
| └── other_transaction_reference_token (String)
|
└── IF: False
├── is_other_transaction_with_same_merchant (Boolean) \- NOTE: Set it to True
|
└── provided_proof_of_other_means_type (Enum)
├── IF: THIRD_PARTY_VOUCHER
| └── is_evidence_of_merchant_passed_funds_provided (Boolean)
├── IF: OTHER_TRANSACTION_ARN
| └── other_visa_transaction_arn (String)
└── IF: OTHER_TRANSACTION_INFORMATION
└── other_visa_transaction_information (String)
```
### INVALID\_DATA
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Transaction was processed despite invalid data in the authorization request.",
"dispute_details": {
"dispute_reason": "INVALID_DATA",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"invalid_data_details": {
"authorization_request_declined_valid_data": true,
"explain_why_valid_data_inclusion_reason": "The authorization request included an expired card number that should have been declined."
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
### NON\_RECEIPT\_OF\_CASH\_OR\_LOAD\_TRANSACTION\_VALUE\_AT\_ATM
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 49.99,
"dispute_reason": "NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM",
"cardholder_contact_date": "2026-01-15T10:30:00Z"
}
}
```
Errors in the Consumer category will have the `dispute_details \-> consumer_dispute_type_dispute_details` object defined.
Below are examples of specific payloads for dispute reasons in the Consumer category.
### SERVICE\_NOT\_PROVIDED\_MERCHANDISE\_NOT\_RECEIVED
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder ordered merchandise that was never delivered.",
"dispute_details": {
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"service_not_provided_merchandise_not_received_details": {
"detailed_description_of_what_was_purchased_and_explanation_of_the_dispute": "Cardholder ordered a blue denim jacket (size M) on January 1, 2024\. Expected delivery was January 15, 2024\. Item was never received and merchant has not responded to two contact attempts.",
"expected_receipt_date": "2026-01-15T00:00:00Z",
"expected_receipt_time": "2026-01-15T17:00:00Z",
"did_cardholder_cancel_prior_to_the_expected_date": false,
"did_cardholder_attempt_to_resolve_dispute_with_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": false,
"merchandise_or_services": "MERCHANDISE",
"was_merchandise_delivered_to_wrong_location": false,
"did_cardholder_return_merchandise": false,
"did_cardholder_attempt_to_return_merchandise": false,
"third_party_gift_card_indicator": false,
"did_merchant_cancel_merchandise": false,
"is_merchant_in_bankruptcy_liquidation": false,
"merchandise_delivered_late": false
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
|
└── service_not_provided_merchandise_not_received_details
|
├── detailed_description_of_what_was_purchased_and_explanation_of_the_dispute (String)
|
├── expected_receipt_date (Date)
| └── IF: expected_receipt_date > today
| └── explanation_dispute_prior_expected_delivery_date (String)
|
├── expected_receipt_time (Date) [Optional]
|
├── did_cardholder_cancel_prior_to_the_expected_date (Boolean)
| └── IF: True
| ├── cancellation_date (Date)
| └── cancellation_reason (String) [Optional]
|
├── did_cardholder_attempt_to_resolve_dispute_with_merchant (Boolean)
|
├── is_attempt_to_resolve_prohibited_by_local_law_or_regulations (Boolean)
| └── IF: True
| └── provide_details_of_local_law_or_regulations (String)
|
├── third_party_gift_card_indicator (Boolean)
|
├── is_merchant_in_bankruptcy_liquidation (Boolean)
|
├── [BRANCH: MERCHANDISE]
| ├── did_merchant_cancel_merchandise (Boolean)
| | └── IF: True
| | └── date_merchant_cancelled_merchandise (Date)
| |
| ├── was_merchandise_delivered_to_wrong_location (Boolean)
| | └── IF: True
| | └── address_of_agreed_location (String)
| |
| └── merchandise_delivered_late (Boolean)
| └── IF: True
| ├── did_cardholder_return_merchandise (Boolean)
| | └── IF: True
| | ├── date_cardholder_returned_merchandise (Date)
| | ├── date_merchant_received_returned_merchandise (Date)
| | └── explain_how_merchandise_was_returned (String) \- (NOTE: Return method enum)
| |
| └── did_cardholder_attempt_to_return_merchandise (Boolean)
| └── IF: True
| ├── date_of_attempted_return (Date)
| └── explain_how_merchandise_was_returned (String)
|
└── [BRANCH: SERVICES]
├── did_merchant_cancel_services (Boolean)
| └── IF: True
| └── date_merchant_cancelled_services (Date)
|
├── non_fiat_currency_not_delivered (Boolean)
|
└── visa_commercial_card_virtual_account_indicator (Boolean) [Optional]
└── IF: True
└── did_virtual_account_holder_suffer_financial_loss (Boolean)
```
### NOT\_AS\_DESCRIBED\_OR\_DEFECTIVE\_MERCHANDISE
The payload for the `NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE` reason code will be different if the cause is Defective or Not-As-Described.
* `NOT_AS_DESCRIBED` value in `not_as_described_or_defective` applies to either MERCHANDISE or SERVICES in `merchandise_or_services`.
* `DEFECTIVE` value in `not_as_described_or_defective` applies only to MERCHANDISE in `merchandise_or_services`.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder received item that does not match the product description.",
"dispute_details": {
"dispute_reason": "NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"not_as_described_or_defective_merchandise_details": {
"not_as_described_or_defective": "NOT_AS_DESCRIBED",
"merchandise_or_services": "MERCHANDISE",
"date_the_cardholder_first_notified_the_issuer_of_the_dispute": "2026-01-20T00:00:00Z",
"did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": false,
"date_merchandise_or_service_was_received": "2026-01-10T00:00:00Z",
"provide_details_of_what_was_ordered_and_not_as_described": "Cardholder ordered a red wool coat but received a blue polyester jacket.",
"did_the_cardholder_return_the_merchandise": true,
"date_cardholder_returned_the_merchandise": "2026-01-18T00:00:00Z",
"date_merchant_received_the_returned_merchandise": "2026-01-21T00:00:00Z",
"return_method": "UPS",
"tracking_number": "1Z999AA10123456784"
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
|
└── not_as_described_or_defective_merchandise_details
|
├── not_as_described_or_defective (Enum: NOT_AS_DESCRIBED | DEFECTIVE)
|
├── [BRANCH: NOT_AS_DESCRIBED]
| ├── date_the_cardholder_first_notified_the_issuer_of_the_dispute (Date)
| |
| └── merchandise_or_services (Enum: MERCHANDISE | SERVICES)
| |
| ├── [BRANCH: MERCHANDISE]
| | ├── date_merchandise_or_service_was_received (Date)
| | ├── provide_details_of_what_was_ordered_and_not_as_described (String)
| | ├── did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant (Boolean)
| | └── did_the_cardholder_return_the_merchandise (Boolean)
| | ├── IF: True
| | | ├── date_cardholder_returned_the_merchandise (Date)
| | | ├── date_merchant_received_the_returned_merchandise (Date)
| | | └── return_method (Enum)
| | | ├── IF: FED_EX | DHL | UPS | POSTAL_SERVICE
| | | | └── tracking_number (String)
| | | └── IF: OTHER
| | | └── explain_how_the_merchandise_was_returned (String)
| | |
| | └── IF: False
| | └── did_the_cardholder_attempt_to_return_the_merchandise (Boolean)
| | └── IF: True
| | ├── date_of_attempted_return (Date)
| | ├── provide_a_detailed_description_of_how_the_cardholder_attempted_to_return... (String)
| | ├── merchant_refuse_advise (Enum)
| | └── what_is_the_disposition_of_the_merchandise (String)
| |
| └── [BRANCH: SERVICES]
| ├── date_merchandise_or_service_was_received (Date)
| ├── provide_details_of_what_was_ordered_and_not_as_described (String)
| ├── did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant (Boolean)
| └── did_the_cardholder_cancel_the_services (Boolean)
| └── IF: True
| ├── cancellation_date (Date)
| └── cancellation_reason (String)
|
└── [BRANCH: DEFECTIVE]
├── date_the_cardholder_first_notified_the_issuer_of_the_dispute (Date)
├── date_merchandise_was_received (Date)
├── what_was_ordered_and_how_it_was_damaged_or_defective (String)
├── did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant (Boolean)
└── did_the_cardholder_return_the_merchandise (Boolean)
├── IF: True
| ├── date_cardholder_returned_the_merchandise (Date)
| ├── date_merchant_received_the_returned_merchandise (Date)
| └── return_method (Enum)
| ├── IF: FED_EX | DHL | UPS | POSTAL_SERVICE
| | └── tracking_number (String)
| └── IF: OTHER
| └── explain_how_the_merchandise_was_returned (String)
|
└── IF: False
└── did_the_cardholder_attempt_to_return_the_merchandise (Boolean)
└── IF: True
├── date_of_attempted_return (Date)
├── provide_a_detailed_description_of_how_the_cardholder_attempted_to_return... (String)
├── merchant_refuse_advise (Enum)
└── what_is_the_disposition_of_the_merchandise (String)
```
### CREDIT\_NOT\_PROCESSED
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder returned merchandise but credit was never applied.",
"dispute_details": {
"dispute_reason": "CREDIT_NOT_PROCESSED",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"credit_not_processed_details": {
"was_a_credit_voucher_voided_transaction_receipt_or_refund_acknowledgement_given": true,
"is_the_credit_voucher_transaction_receipt_or_refund_acknowledgement_dated": true,
"credit_voucher_transaction_receipt_or_refund_acknowledgement_date": "2026-01-15T00:00:00Z"
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
|
└── credit_not_processed_details
|
└── was_a_credit_voucher_voided_transaction_receipt_or_refund_acknowledgement_given (Boolean)
| (NOTE: Must be True to submit)
|
└── is_the_credit_voucher_transaction_receipt_or_refund_acknowledgement_dated (Boolean)
|
├── IF: True
| └── credit_voucher_transaction_receipt_or_refund_acknowledgement_date (Date)
|
└── IF: False
└── date_cardholder_returned_cancelled_merchandise (Date)
```
### CANCELLED\_RECURRING\_TRANSACTION
Either `cancellation_date` or `date_issuer_informed_merchant_of_account_closure` must be defined under `cancelled_recurring_transaction_details`.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder cancelled subscription but was charged again the following month.",
"dispute_details": {
"dispute_reason": "CANCELLED_RECURRING_TRANSACTION",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"cancelled_recurring_transaction_details": {
"cancellation_date": "2026-01-01T00:00:00Z",
"cancellation_reason": "Cardholder no longer uses the service.",
"contact_method_with_merchant_ind": true,
"contact_method_merchant_email_ind": true,
"contact_merchant_details_email_address": "support@merchant.com",
"other_form_of_payment_ind": false,
"is_dispute_impacted_by_local_law_or_regulation": false
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
|
└── cancelled_recurring_transaction_details
|
├── cancellation_date (Date) [Optional]
| └── IF: defined
| ├── cancellation_reason (String)
| |
| ├── other_form_of_payment_ind (Boolean)
| | └── IF: True
| | └── other_form_of_payment_desc (String)
| |
| └── contact_method_with_merchant_ind (Boolean)
| └── IF: True
| ├── contact_method_merchant_email_ind (Boolean)
| | └── IF: True \-> contact_merchant_details_email_address (String)
| |
| ├── contact_method_merchant_call_center_ind (Boolean)
| | └── IF: True \-> contact_merchant_details_phone_number (String)
| |
| ├── contact_method_merchant_mail_ind (Boolean)
| | └── IF: True \-> contact_merchant_details_physical_address (String)
| |
| ├── contact_method_merchant_webform_ind (Boolean)
| | └── IF: True \-> contact_merchant_details_application_name (String)
| |
| ├── contact_method_merchant_SMS_ind (Boolean)
| └── contact_method_merchant_in_person_ind (Boolean)
|
├── date_issuer_informed_merchant_of_account_closure (Date) [Optional]
|
└── is_dispute_impacted_by_local_law_or_regulation (Boolean)
```
### CANCELLED\_MERCHANDISE\_OR\_SERVICES
The payload for the `CANCELLED_MERCHANDISE_OR_SERVICES` reason code will be different if the cancellation applies to merchandise or a service.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder cancelled order within the merchant's stated policy window but was not refunded.",
"dispute_details": {
"dispute_reason": "CANCELLED_MERCHANDISE_OR_SERVICES",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"consumer_dispute_type_dispute_details": {
"cancelled_merchandise_or_services_details": {
"merchandise_or_services": "MERCHANDISE",
"describe_what_was_purchased": "Blue denim jacket, size M",
"date_cardholder_received_or_expected_to_receive_merchandise": "2026-01-10T00:00:00Z",
"did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant": true,
"is_attempt_to_resolve_prohibited_by_local_law_or_regulations": false,
"did_the_cardholder_return_the_merchandise": true,
"date_of_return": "2026-01-15T00:00:00Z",
"date_merchant_received_returned_merchandise": "2026-01-18T00:00:00Z",
"return_method": "UPS",
"tracking_number": "1Z999AA10123456784",
"explain_how_the_merchandise_was_returned": "Cardholder dropped off the package at a UPS store and received a receipt.",
"did_the_cardholder_attempt_to_return_the_merchandise": true,
"date_of_attempted_return": "2026-01-14T00:00:00Z",
"detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise": "Cardholder contacted merchant via email on January 14 to initiate return; merchant provided a prepaid UPS label.",
"what_is_the_disposition_of_the_merchandise": "Returned to merchant via UPS on January 15.",
"did_cardholder_cancel": true,
"cancellation_date": "2026-01-13T00:00:00Z",
"cancellation_reason": "Item did not match description on website.",
"was_cancellation_policy_provided": true,
"merchant_refuse_advise": "MERCHANT_REFUSED_RETURN_AUTHORIZATION",
"type_of_service": "OTHER",
"date_of_service_or_expected_service": "2026-01-10T00:00:00Z",
"cancelled_guaranteed_reservation_certification_selection": "CARDHOLDER_PROPERLY_CANCELLED"
}
}
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
└── cancelled_merchandise_or_services_details
|
├── merchandise_or_services (BRANCH: MERCHANDISE)
| |
| ├── describe_what_was_purchased (String)
| ├── did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant (Boolean)
| | └── IF: False
| | └── is_attempt_to_resolve_prohibited_by_local_law_or_regulations (Boolean)
| |
| ├── did_cardholder_cancel (Boolean)
| | ├── IF: True
| | | ├── cancellation_date (Date)
| | | ├── cancellation_reason (String)
| | | └── was_cancellation_policy_provided (Boolean)
| | └── IF: False
| | └── was_cancellation_policy_provided (Boolean)
| |
| └── [CONTEXT: DID CARDHOLDER RECEIVE MERCHANDISE?]
| ├── IF: YES (Received)
| | ├── date_cardholder_received_or_expected_to_receive_merchandise (Date)
| | └── did_the_cardholder_return_the_merchandise (Boolean)
| | ├── IF: True
| | | ├── date_of_return (Date)
| | | ├── date_merchant_received_returned_merchandise (Date)
| | | └── return_method (Enum)
| | | ├── IF: FED_EX | DHL | UPS | POSTAL_SERVICE \-> tracking_number (String)
| | | └── IF: OTHER \-> explain_how_the_merchandise_was_returned (String)
| | └── IF: False
| | └── did_the_cardholder_attempt_to_return_the_merchandise (Boolean)
| | └── IF: True
| | ├── date_of_attempted_return (Date)
| | ├── detailed_description_of_how_the_cardholder_attempted_to_return_and_the_disposition_of_the_merchandise (String)
| | ├── what_is_the_disposition_of_the_merchandise (String)
| | └── merchant_refuse_advise (Enum)
| └── IF: NO (Not Received)
| └── date_cardholder_received_or_expected_to_receive_merchandise (Date)
|
└── merchandise_or_services (BRANCH: SERVICES)
└── type_of_service (Enum: TIMESHARE | GUARANTEED_RESERVATION | OTHER)
├── [BRANCH: TIMESHARE]
| ├── did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant (Boolean)
| | └── IF: False \-> is_attempt_to_resolve_prohibited_by_local_law_or_regulations (Boolean)
| └── did_cardholder_cancel (Boolean)
| ├── IF: True \-> cancellation_date (Date), cancellation_reason (String), date_of_service_or_expected_service (Date)
| └── IF: False \-> date_of_service_or_expected_service (Date)
├── [BRANCH: GUARANTEED_RESERVATION]
| ├── did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant (Boolean)
| | └── IF: False \-> is_attempt_to_resolve_prohibited_by_local_law_or_regulations (Boolean)
| ├── was_cancellation_policy_provided (Boolean)
| ├── date_of_service_or_expected_service (Date)
| └── cancelled_guaranteed_reservation_certification_selection (Enum)
| ├── IF: CARDHOLDER_PROPERLY_CANCELLED \-> cancellation_date (Date)
| └── IF: CARDHOLDER_ATTEMPTED_TO_CANCEL_WITHIN_24_HOURS_OF_CONFIRMATION \-> cancellation_date (Date)
└── [BRANCH: OTHER]
├── describe_what_was_purchased (String)
├── date_of_service_or_expected_service (Date)
├── cancellation_date (Date)
├── cancellation_reason (String)
├── did_the_cardholder_attempt_to_resolve_the_dispute_with_the_merchant (Boolean)
| └── IF: False \-> is_attempt_to_resolve_prohibited_by_local_law_or_regulations (Boolean)
└── was_cancellation_policy_provided (Boolean)
```
### COUNTERFEIT\_MERCH
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder received merchandise identified as counterfeit by the IP owner.",
"dispute_details": {
"dispute_reason": "COUNTERFEIT_MERCH",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"counterfeit_merch_details": {
"what_was_ordered": "Limited edition designer handbag",
"date_the_cardholder_received_the_merchandise_or_notification": "2026-01-10T00:00:00Z",
"describe_the_counterfeit_merchandise": "The bag lacks official authentication tags and stitching quality is inconsistent with genuine products.",
"describe_the_disposition_of_counterfeit_merchandise": "Cardholder retained the item pending dispute resolution.",
"provide_information_about_the_entity_that_indicated_the_merchandise_to_be_counterfeit": "Brand's authorized representative confirmed counterfeit via email on January 20, 2024.",
"certification_the_merchandise_was_identified_as_counterfeit_by_one_of_the_following": "THE_OWNER_OF_THE_INTELLECTUAL_PROPERTY_OR_ITS_AUTHORIZED_REPRESENTATIVE"
}
},
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f"
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
|
└── counterfeit_merch_details
|
├── what_was_ordered (String)
|
├── date_the_cardholder_received_the_merchandise_or_notification (Date)
|
├── describe_the_counterfeit_merchandise (String)
|
├── describe_the_disposition_of_counterfeit_merchandise (String)
|
└── [CONTEXT: Visa Network Mandate H1 2025 \== FALSE]
|
├── provide_information_about_the_entity_that_indicated_the_merchandise_to_be_counterfeit (String)
|
└── certification_the_merchandise_was_identified_as_counterfeit_by_one_of_the_following (Enum)
(Values: IP_OWNER | CUSTOMS_GOVT_AGENCY | THIRD_PARTY_EXPERT)
```
### MISREPRESENTATION
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder received a product that was materially misrepresented in the merchant's listing.",
"dispute_details": {
"dispute_reason": "MISREPRESENTATION",
"dispute_amount": 110.01,
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"consumer_dispute_type_dispute_details": {
"misrepresentation_details": {
"merchandise_or_services": "MERCHANDISE",
"merchandise_received_date": "2026-01-10T00:00:00Z",
"describe_what_was_purchased": "Wireless noise-cancelling headphones, model XZ-500",
"how_merchandise_service_misrepresented": "Merchant advertised 40-hour battery life; actual battery life is under 8 hours.",
"cardholder_attempt_to_resolve": true,
"attempt_to_resolve_proh_local_law": false,
"cardholder_return_merchandise_ind": true,
"cardholder_returned_merchandise_date": "2026-01-18T00:00:00Z",
"merchant_received_returned_merchandise_date": "2026-01-21T00:00:00Z",
"return_method": "UPS",
"shipping_tracking_number": "1Z999AA10123456784"
}
}
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
|
└── misrepresentation_details
|
├── merchandise_or_services (Enum: MERCHANDISE | SERVICES)
|
├── [BRANCH: MERCHANDISE]
| ├── merchandise_received_date (Date)
| ├── describe_what_was_purchased (String)
| ├── how_merchandise_service_misrepresented (String)
| ├── cardholder_attempt_to_resolve (Boolean)
| | └── IF: False \-> attempt_to_resolve_proh_local_law (Boolean)
| |
| └── cardholder_return_merchandise_ind (Boolean)
| ├── IF: True
| | ├── cardholder_returned_merchandise_date (Date)
| | ├── merchant_received_returned_merchandise_date (Date)
| | └── return_method (Enum)
| | ├── IF: FED_EX | DHL | UPS | POSTAL_SERVICE \-> shipping_tracking_number (String)
| | └── IF: OTHER \-> how_merchandise_returned (String)
| |
| └── IF: False
| └── cardholder_attempt_return_merchandise (Boolean)
| └── IF: True
| ├── attempted_return_date (Date)
| ├── how_ch_attempt_return_and_disp_of_merchandise (String)
| └── merchant_refuse_ind (Enum)
|
└── [BRANCH: SERVICES]
├── merchandise_received_date (Date)
├── service_received_date (Date)
├── describe_what_was_purchased (String)
├── how_merchandise_service_misrepresented (String)
├── cardholder_attempt_to_resolve (Boolean)
| └── IF: False \-> attempt_to_resolve_proh_local_law (Boolean)
|
└── did_cardholder_cancel (Boolean)
└── IF: True
├── cancellation_date (Date)
└── cancellation_reason (String)
```
Fraud reports record fraudulent activity for card network reporting purposes but do not initiate chargeback recovery.
Use this reason code to report fraud types such as lost or stolen cards, account takeover, or counterfeit card fraud.
### FRAUD\_REPORT
For fraud reports, the payload will be different when the fraud type is set to `MANIPULATION_OF_ACCOUNT_HOLDER`.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder confirmed account takeover. Three unauthorized transactions identified.",
"dispute_details": {
"dispute_reason": "FRAUD_REPORT",
"dispute_amount": 342.50,
"original_transaction_token": "1c0a45c3-8212-4524-b679-610cf4d231a8",
"cardholder_contact_date": "2026-03-12T11:30:00Z",
"fraud_category_type_dispute_details": {
"fraud_type": "ACCOUNT_OR_CREDENTIALS_TAKEOVER"
}
}
}
```
```text Dependency Diagram theme={null}
dispute_details
|
└── fraud_category_type_dispute_details
|
└── fraud_type (Enum)
|
├── [BRANCH: ALL TYPES \- except MANIPULATION_OF_ACCOUNT_HOLDER]
| (LOST, STOLEN, CARD_NOT_RECEIVED_AS_ISSUED, FRAUDULENT_APPLICATION,
| ISSUER_REPORTED_COUNTERFEIT, MISCELLANEOUS, FRAUDULENT_USE_OF_ACCOUNT_NUMBER,
| INCORRECT_PROCESSING, ACCOUNT_OR_CREDENTIALS_TAKEOVER, MERCHANT_MISREPRESENTATION)
| No additional fields required.
|
└── [BRANCH: MANIPULATION_OF_ACCOUNT_HOLDER]
|
└── fraud_classification_type_dispute_details
└── fraud_type_classification (Enum)
(Values: PURCHASE_SCAM, INVESTMENT_SCAM, ROMANCE_SCAM,
ADVANCE_FEE_SCAM, INVOICE_OR_MANDATE_SCAM,
CEO_FRAUD_SCAM, IMPERSONATION_SCAM)
```
Authorization disputes cover transactions that were processed without valid authorization.
Use the reason codes in this category when a transaction was declined, processed against a closed account, or lacked a valid authorization.
### NO\_AUTHORIZATION
For `NO_AUTHORIZATION` you must include `account_status`.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"dispute_reason": "NO_AUTHORIZATION",
"dispute_amount": 10.01,
"original_transaction_token": "0bbf0259-bc8b-46f1-a2de-76135d5993eb",
"cardholder_contact_date": "2026-05-01T01:00:00Z",
"account_status": "FRAUD"
}
}
```
### ORIGINAL\_CREDIT\_NOT\_ACCEPTED
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"dispute_reason": "ORIGINAL_CREDIT_NOT_ACCEPTED",
"dispute_amount": 10.01,
"original_transaction_token": "0bbf0259-bc8b-46f1-a2de-76135d5993eb",
"cardholder_contact_date": "2026-05-01T01:00:00Z"
}
}
```
### DECLINED\_AUTH
For `DECLINED_AUTH` you must include `account_status`.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"dispute_amount": 22.10,
"dispute_reason": "DECLINED_AUTH",
"original_transaction_token": "75a1d6d5-01f8-4c9a-b89d-ecf80658e801",
"account_status": "ACCOUNT_CLOSED",
"cardholder_contact_date": "2026-02-25T17:06:00Z"
}
}
```
### CARD\_RECOVERY\_BULLETIN
For `CARD_RECOVERY_BULLETIN` you must include `account_status`.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"dispute_details": {
"original_transaction_token": "75a1d6d5-01f8-4c9a-b89d-ecf80658e801",
"dispute_amount": 150.00,
"dispute_reason": "CARD_RECOVERY_BULLETIN",
"account_status": "CREDIT_PROBLEM",
"cardholder_contact_date": "2026-01-15T10:30:00Z"
}
}
```
Mastercard dispute payloads generally require the core dispute fields and the `network_comment` field explaining the dispute context, with additional fields required for fraud reports.
This section covers all standard dispute reason codes as well as a separate Fraud Report payload that requires additional fraud classification fields.
This tab covers all non-fraud Mastercard dispute reason codes, which share a common payload structure.
* Use the `network_comment` field to provide dispute context for the card network.
* Use the `memo` field for internal comments.
* For fraud reports, see the [Fraud Report tab](#).
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Internal case notes go here.",
"network_comment": "Cardholder cancelled subscription on January 15 via merchant portal and received confirmation. Merchant continued to bill $14.99 on February 1 and March 1.",
"dispute_details": {
"original_transaction_token": "75a1d6d5-01f8-4c9a-b89d-ecf80658e801",
"dispute_amount": 14.99,
"dispute_reason": "CANCELLED_RECURRING_TRANSACTION",
"cardholder_contact_date": "2026-03-05T14:00:00Z"
}
}
```
**Supported reason codes:**
* `CANCELLED_RECURRING_TRANSACTION`
* `CARDHOLDER_DISPUTE`
* `CARDHOLDER_DISPUTE_US_ONLY`
* `CHIP_LIABILITY_SHIFT`
* `CHIP_PIN_LIABILITY_SHIFT_LOST_STOLEN`
* `CHIP_READ_POS_LATE_PRESENTMENT`
* `DOMESTIC_CHARGEBACK_INTRA_EUROPEAN_USE`
* `DUPLICATE_PROCESSING_OR_PAID_BY_OTHER_MEANS`
* `INCORRECT_CURRENCY_OR_TRANSACTION_CODE`
* `INSTALLMENT_BILLING_DISPUTE`
* `NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM`
* `NOT_AUTHORIZED_CARD_ABSENT`
* `NOT_AUTHORIZED_CARD_PRESENT`
* `NO_AUTHORIZATION`
* `POINT_OF_INTERACTION_ERRORS`
* `QUESTIONABLE_MERCHANT_ACTIVITY`
When submitting a fraud report, include `mastercard_fraud_report_details` with `fraud_type` and `sub_type` as child parameters.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder confirmed card was stolen. Three unauthorized transactions identified.",
"dispute_details": {
"original_transaction_token": "1c0a45c3-8212-4524-b679-610cf4d231a8",
"dispute_amount": 215.40,
"currency_code": "USD",
"dispute_reason": "FRAUD_REPORT",
"cardholder_contact_date": "2026-03-12T11:30:00Z",
"mastercard_fraud_report_details": {
"fraud_type": "STOLEN",
"sub_type": "PIN_NOT_USED_IN_TRANSACTION"
}
}
}
```
PULSE dispute payloads require the core dispute fields, with additional detail objects available for select reason codes.
This section covers the Consumer, Processing Error, and Non-Cardholder Reasons dispute categories, spanning a total of 17 reason codes.
### SERVICE\_NOT\_PROVIDED\_MERCHANDISE\_NOT\_RECEIVED
`agreed_delivery_date_or_service_date` is required if the case is filed within 16 days of settlement.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder did not receive merchandise ordered online.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"service_not_provided_merchandise_not_received_details": {
"agreed_delivery_date_or_service_date": "2026-01-15T00:00:00Z",
"date_of_return": "2026-01-12",
"cash_over_indicator": "M"
}
}
}
}
```
```text Dependency Diagram theme={null}
consumer_dispute_type_dispute_details
│
└── service_not_provided_merchandise_not_received_details
│
├── agreed_delivery_date_or_service_date (Date, optional*)
│ * Required if case filed within 16 days of settlement date
│
├── date_of_return (Date, optional)
│
└── cash_over_indicator (Enum, optional: M | C | B)
├── M \= "Merchandise only"
├── C \= "Cash over only"
└── B \= "Both Merchandise and cash"
```
### CANCELLED\_RECURRING\_TRANSACTION
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder cancelled recurring payment but was still charged.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "CANCELLED_RECURRING_TRANSACTION",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"cancelled_recurring_transaction_details": {
"cancelled_recurring_payment_date": "2026-01-01T00:00:00Z",
"recurring_payment_plan_expiry_date": "2026-01-31T00:00:00Z"
}
}
}
}
```
### NOT\_AS\_DESCRIBED\_OR\_DEFECTIVE\_MERCHANDISE
`motive_code` is a required field.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder received merchandise that does not match the description.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"not_as_described_or_defective_merchandise_details": {
"motive_code": "QUALITY_OF_GOODS_OR_SERVICES",
"merchandise_counterfeit_confirmation_date": "2026-01-18T00:00:00Z",
"promised_delivery_date": "2026-01-10T00:00:00Z",
"cash_over_indicator": "M"
}
}
}
}
```
### CREDIT\_NOT\_PROCESSED
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder returned merchandise but credit was never applied to their account.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "CREDIT_NOT_PROCESSED",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"consumer_dispute_type_dispute_details": {
"credit_not_processed_details": {
"date_of_cancellation": "2026-01-05",
"date_of_return": "2026-01-10",
"cash_over_indicator": "M"
}
}
}
}
```
### CANCELLED\_MERCHANDISE\_OR\_SERVICES
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder cancelled order but merchant did not issue a refund.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "CANCELLED_MERCHANDISE_OR_SERVICES",
"cardholder_contact_date": "2026-01-24T23:00:00Z"
}
}
```
### NON\_RECEIPT\_OF\_CASH\_OR\_LOAD\_TRANSACTION\_VALUE\_AT\_ATM
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder did not receive cash from ATM withdrawal.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM",
"cardholder_contact_date": "2026-01-24T23:00:00Z"
}
}
```
### NOT\_AUTHORIZED\_CARD\_ABSENT
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder did not authorize this card-absent transaction.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT",
"cardholder_contact_date": "2026-01-24T23:00:00Z"
}
}
```
### EMV\_LIABILITY\_SHIFT\_NON\_COUNTERFEIT\_FRAUD
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "EMV liability shift dispute for non-counterfeit fraud.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "EMV_LIABILITY_SHIFT_NON_COUNTERFEIT_FRAUD",
"cardholder_contact_date": "2026-01-24T23:00:00Z"
}
}
```
### EMV\_LIABILITY\_SHIFT\_COUNTERFEIT\_FRAUD
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "EMV liability shift dispute for counterfeit card fraud.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "EMV_LIABILITY_SHIFT_COUNTERFEIT_FRAUD",
"cardholder_contact_date": "2026-01-24T23:00:00Z"
}
}
```
### NOT\_AUTHORIZED\_CARD\_PRESENT
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder did not authorize this card-present transaction.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "NOT_AUTHORIZED_CARD_PRESENT",
"cardholder_contact_date": "2026-01-24T23:00:00Z"
}
}
```
### NO\_AUTHORIZATION
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Transaction processed without authorization.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 25.00,
"dispute_reason": "NO_AUTHORIZATION",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"no_authorization_details": {
"cash_over_indicator": "M"
}
}
}
}
```
### LATE\_PRESENTMENT
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Transaction presented after the allowable presentment window.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 25.00,
"dispute_reason": "LATE_PRESENTMENT",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"late_presentment_details": {
"cash_over_indicator": "M"
}
}
}
}
```
### INCORRECT\_ACCOUNT\_NUMBER
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Transaction posted to an incorrect account number.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 25.00,
"dispute_reason": "INCORRECT_ACCOUNT_NUMBER",
"cardholder_contact_date": "2026-01-24T23:00:00Z"
}
}
```
### INCORRECT\_TRANSACTION\_AMOUNT
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder was charged an incorrect amount for this transaction.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 25.00,
"dispute_reason": "INCORRECT_TRANSACTION_AMOUNT",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"incorrect_transaction_amount_details": {
"cash_over_indicator": "M"
}
}
}
}
```
### INCORRECT\_TRANSACTION\_CODE
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Transaction was processed with an incorrect transaction code.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 25.00,
"dispute_reason": "INCORRECT_TRANSACTION_CODE",
"cardholder_contact_date": "2026-01-24T23:00:00Z",
"processing_error_type_dispute_details": {
"incorrect_transaction_code_details": {
"credit_confirmation_number": "REF-123456",
"date_of_return": "2026-06-20",
"return_method": "UPS"
}
}
}
}
```
### Duplicate Processing
PULSE supports two distinct reason codes for duplicate charge disputes.
They differ in network scope, when to use them, and how the dispute amount is handled when the case is submitted to the PULSE network.
#### DUPLICATE\_PROCESSING
**PULSE code:** 4534 | **Networks:** PULSE only
Use this when the cardholder was charged twice for the exact same transaction and no alternate payment was involved.
This is a PULSE-exclusive reason code — it has no Visa or Mastercard equivalent.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder was charged twice for the same transaction.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "DUPLICATE_PROCESSING",
"cardholder_contact_date": "2025-01-15T10:30:00Z"
}
}
```
#### DUPLICATE\_PROCESSING\_OR\_PAID\_BY\_OTHER\_MEANS
**PULSE code:** 4865 | **Networks:** Visa (12.6), Mastercard (73), PULSE (4865)
Use this when the transaction was processed twice, or the cardholder already paid for the goods or services by another method such as cash, check, or gift card.
This reason code works across all three networks.
For PULSE, use this reason code when payment is made by other means.
The `dispute_amount` is forwarded to the PULSE network when the case is submitted.
```json Flat Payload theme={null}
{
"type": "DISPUTE",
"memo": "Cardholder was charged twice for the same transaction.",
"dispute_details": {
"original_transaction_token": "c14fed48-b3f5-435e-99f2-743cbff97a0f",
"dispute_amount": 50.00,
"dispute_reason": "DUPLICATE_PROCESSING_OR_PAID_BY_OTHER_MEANS",
"cardholder_contact_date": "2025-01-15T10:30:00Z"
}
}
```
## Related topics
- [Creating a Dispute](/docs/developer-guides/disputes-portal-create.md)
- [Disputes in the Marqeta Dashboard](/docs/developer-guides/disputes-dashboard.md)
- [Create, Submit, and Manage a Dispute](/docs/developer-guides/disputes-sandbox/disputes-sandbox-submit-manage.md)
- [Disputes Sandbox Overview](/docs/developer-guides/disputes-sandbox/disputes-sandbox-overview.md)
- [Disputes (PULSE)](/docs/core-api/disputes-pulse.md)