> ## 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. # Create dispute case > Create a new dispute case by specifying the type and including the type-specific details object. POST/cases Create a new dispute case by specifying the type and including the type-specific details object. ## Body field details | Fields | Description | | - | - | | token string Optional | Unique identifier of the dispute case. If you do not include a token, the system generates one automatically. Because this token is necessary for use in other API calls, it is recommended that, rather than let the system generate the token, you use a simple string that is easy to remember. This value cannot be updated. **Allowable Values:** 36 char max | | type string Required | Type of dispute case. **Allowable Values:** `DISPUTE` | | memo string Optional | Free-form comments about the dispute. **Allowable Values:** 512 char max | | network\_comment string Optional | Comment provided by the cardholder to be sent to the PULSE card network. **Allowable Values:** 500 char max, with the following allowed and disallowed characters: **Allowed Characters:** `%` `&` `*` `(` `)` `_` `-` `+` `'` `:` `,` `.` `` ` `` `,` `?` `/` **Disallowed Characters:** `!` `@` `#` `$` `^` `=` `[` `]` `{` `}` `"` `;` `<` `>` `\` `\|` | | salesforce\_ticket\_id string Optional | Identifier of the associated Salesforce ticket. **Allowable Values:** 255 char max | | dispute\_details object Required | Object describing the disputed transaction, including the reason for the dispute. **Allowable Values:** See [The dispute\_details object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_dispute_details_object) table. | ## The dispute\_details object Include this object in your request if the case type is `DISPUTE`. | Fields | Description | | - | - | | original\_transaction\_token string Required | Unique identifier of the original transaction under dispute. **Allowable Values:** 36 char max | | original\_transaction\_type string Required | Transaction type of the original transaction under dispute. **Allowable Values:** 255 char max | | dispute\_amount number Required | Amount of funds under dispute. **Allowable Values:** Must be less than or equal to the original transaction amount | | dispute\_reason string Required | Code describing the reason for the dispute. **Allowable Values:** See [The dispute\_details.dispute\_reason field](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_dispute_details_dispute_reason_field) table. | | cardholder\_contact\_date datetime Required | Date that the cardholder made initial contact regarding the dispute. **Allowable Values:** Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ | | cancelled\_recurring\_payment\_date string Optional | Date that the recurring payment was cancelled. Optional field for `CANCELLED_RECURRING_TRANSACTION` disputes. **Allowable Values:** Format: yyyy-MM-dd | | recurring\_payment\_plan\_expiry\_date string Required | Date that the recurring payment plan expired. Optional field for `CANCELLED_RECURRING_TRANSACTION` disputes. **Allowable Values:** Format: yyyy-MM-dd | | cash\_over\_indicator string Optional | Indicates the disputed portion of the transaction. - **M** indicates that the merchandise portion of the transaction is in dispute. - **C** indicates that the cash portion of the transaction is in dispute. - **B** indicates that both the merchandise and cash portions of the transaction are in dispute. Conditionally required field for `CREDIT_NOT_PROCESSED` disputes that do not include the `date_of_return` field. Optional field for `INCORRECT_TRANSACTION_AMOUNT`, `LATE_PRESENTMENT`, `NO_AUTHORIZATION`, `NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE`, and `SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED` disputes **Allowable Values:** `M`, `C`, `B` | | comments string Optional | Freeform text comments provided by the cardholder. Optional field for `INCORRECT_TRANSACTION_AMOUNT` and `INCORRECT_TRANSACTION_CODE` disputes. **Allowable Values:** 500 char max | | credit\_confirmation\_number string Optional | Reference number for the credit that was provided to the cardholder. Optional field for `INCORRECT_TRANSACTION_CODE` disputes. **Allowable Values:** 25 char max | | date\_of\_return string Optional | Date on which the merchandise was returned to the merchant. Conditionally required field for `CREDIT_NOT_PROCESSED` disputes that do not include the `cash_over_indicator` field. Optional field for `INCORRECT_TRANSACTION_CODE` and `SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED` disputes. **Allowable Values:** Format: yyyy-MM-dd | | return\_method string Optional | Code that indicates the method by which the merchandise was returned to the merchant. - **F2F** indicates that the merchandise was returned in person. - **FEDEX** indicates that the merchandise was returned by FedEx. - **DHL** indicates that the merchandise was returned by DHL. - **POSTAL\_SERVICE** indicates that the merchandise was returned by the Postal Service. - **UPS** indicates that the merchandise was returned by UPS. - **OTHER** indicates that the merchandise was returned by other means. Optional field for `INCORRECT_TRANSACTION_CODE` disputes. **Allowable Values:** `F2F`, `FEDEX`, `DHL`, `POSTAL_SERVICE`, `UPS`, `OTHER` | | motive\_code string Optional | Code that indicates additional return reason details. - **QUALITY\_OF\_GOODS\_OR\_SERVICES** indicates that the cardholder disputes the quality of the goods received or services rendered. - **TERMS\_OF\_SALE\_OR\_COUNTERFEIT\_MERCHANDISE** indicates that the cardholder disputes the terms of sale, or that the merchandise is counterfeit. Required field for `NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE` disputes. **Allowable Values:** `QUALITY_OF_GOODS_OR_SERVICES`, `TERMS_OF_SALE_OR_COUNTERFEIT_MERCHANDISE` | | merchandise\_counterfeit\_confirmation\_date string Optional | Date that the merchandise was determined to be counterfeit. Optional field for `NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE` disputes. **Allowable Values:** Format: yyyy-MM-dd | | promised\_delivery\_date string Optional | Date that the merchandise was due to be delivered, or the service was due to be performed. Optional field for `NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE` disputes. **Allowable Values:** Format: yyyy-MM-dd | | agreed\_delivery\_or\_service\_date string Conditionally required | Date of delivery or service agreed upon by both merchant and cardholder. Used for non-receipt of goods or services disputes. This field is required if the dispute is submitted within 15 days of the settlement date. This field is optional if the dispute is submitted 16 or more days after the original settlement date. **Allowable Values:** Format: yyyy-MM-dd | | date\_of\_cancellation string Optional | Date on which the merchandise or service order was cancelled. Optional field for `CREDIT_NOT_PROCESSED` disputes. **Allowable Values:** Format: yyyy-MM-dd | ## The dispute\_details.dispute\_reason field The following table describes the possible values for the `dispute_details.dispute_reason` field. | Dispute Reason | Description | | - | - | | `CANCELLED_RECURRING_TRANSACTION` | A recurring transaction was cancelled. | | `CREDIT_NOT_PROCESSED` | A credit was not processed. | | `DUPLICATE_PROCESSING` | A single transaction was processed more than once using the same payment credential on the same transaction date, and for the same transaction amount. | | `DUPLICATE_PROCESSING_OR_PAID_BY_OTHER_MEANS` | A single transaction was paid by other means. Use this dispute reason only for "paid by other means" disputes. For duplicate processing disputes, use `DUPLICATE_PROCESSING` | | `EMV_LIABILITY_SHIFT_COUNTERFEIT_FRAUD` | The transaction was completed with a counterfeit card in a card-present environment and qualifies for the EMV liability shift. | | `EMV_LIABILITY_SHIFT_NON_COUNTERFEIT_FRAUD` | The transaction was completed in a card-present environment with a card that was reported lost or stolen and qualifies for the EMV liability shift. | | `INCORRECT_ACCOUNT_NUMBER` | The account number is incorrect. | | `INCORRECT_TRANSACTION_AMOUNT` | The transaction amount is incorrect. | | `INCORRECT_TRANSACTION_CODE` | The transaction code is incorrect. | | `LATE_PRESENTMENT` | The card network cannot verify that the transaction amount was deposited within 30 days. | | `NO_AUTHORIZATION` | - Authorization was required, but not obtained. - The primary account number (PAN) does not exist. - A Card Not Present (CNP) transaction was initially declined but subsequently approved through stand-in processing. | | `NON_RECEIPT_OF_CASH_OR_LOAD_TRANSACTION_VALUE_AT_ATM` | The cardholder did not receive the full cash withdrawal or received only partial amount. | | `NOT_AS_DESCRIBED_OR_DEFECTIVE_MERCHANDISE` | The merchandise was not as described or defective. | | `NOT_AUTHORIZED_CARD_ABSENT` | An unauthorized user initiated the transaction and the card was not present. | | `NOT_AUTHORIZED_CARD_PRESENT` | The cardholder denies authorization of or participation in a key-entered transaction conducted in a card-present environment. | | `SERVICE_NOT_PROVIDED_MERCHANDISE_NOT_RECEIVED` | The goods or services were not provided. | ### The pulseProcessingDisputeTypeDetails object | Fields | Description | | - | - | | late\_presentment\_details object Conditionally required | An object providing late presentment details. **Allowable Values:** See [The late\_presentment\_details object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_late_presentment_details_object) table. | | incorrect\_transaction\_code\_details object Conditionally required | An object providing incorrect transaction code details. **Allowable Values:** See [The incorrect\_transaction\_code\_details object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_incorrect_transaction_code_details_object) table. | | incorrect\_currency\_details object Conditionally required | An object providing incorrect currency details. **Allowable Values:** See [The incorrect\_currency\_details object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_incorrect_currency_details_object) table. | | incorrect\_account\_number\_details object Conditionally required | An object providing incorrect account number details. **Allowable Values:** See [The incorrect\_account\_number\_details object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_incorrect_account_number_details_object) table. | | incorrect\_transaction\_amount\_details object Conditionally required | An object providing incorrect transaction amount details. **Allowable Values:** See [The incorrect\_transaction\_amount\_details object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_incorrect_transaction_amount_details_object) table. | | duplicate\_processing\_or\_paid\_by\_other\_means\_details object Conditionally required | An object providing details about duplicate processing or paid by other means. **Allowable Values:** See [The duplicate\_processing\_or\_paid\_by\_other\_means\_details object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/create-dispute-case-pulse.md#_the_duplicate_processing_or_paid_by_other_means_details_object) table. | The late\_presentment\_details object | Fields | Description | | - | - | | account\_status string Conditionally required | The account status. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** `ACCOUNT_CLOSED`, `CREDIT_PROBLEM`, `FRAUD`, `NONSUFFICIENT_FUNDS` | The incorrect\_transaction\_code\_details object | Fields | Description | | - | - | | how\_is\_transaction\_code\_incorrect string Conditionally required | The token of the original transaction under dispute. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** `CREDIT_INSTEAD_OF_REVERSAL_OR_ADJUSTMENT`, `CREDIT_POSTED_AS_DEBIT`, `DEBIT_POSTED_AS_CREDIT` | | explain\_why\_the\_credit\_refund\_was\_processed\_in\_error string Conditionally required | An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** | The incorrect\_currency\_details object | Fields | Description | | - | - | | incorrect\_currency\_reason string Conditionally required | The reason for the incorrect currency. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** `CURRENCY_DIFFERENCE`, `DCC_DISPUTE` | | what\_was\_the\_correct\_currency integer Conditionally required | An explanation for why the credit refund was incorrectly processed. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** ISO 4217 currency number | | certification\_that\_the\_cardholder\_did\_not\_agree\_to\_dynamic\_currency\_conversion\_and\_did\_not\_make\_an\_active\_choice string Conditionally required | Indicates that the cardholder did not agree to or make an active choice for dynamic currency conversion. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** `true`, `false` | The incorrect\_account\_number\_details object | Fields | Description | | - | - | | is\_the\_account\_number\_on\_the\_issuers\_master\_file boolean Conditionally required | Indicates whether the cardholder's account number is also in the issuer's file. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** `true`, `false` | | does\_the\_account\_number\_on\_the\_receipt\_match\_the\_cardholders\_account\_number\_or\_token boolean Conditionally required | Indicates whether the account numbers match. Whether this field is optional or required depends on previous answers provided by the cardholder. **Allowable Values:** `true`, `false` | The incorrect\_transaction\_amount\_details object | Fields | Description | | - | - | | what\_is\_the\_amount\_on\_the\_cardholders\_receipt number Conditionally required | The amount on the cardholder's receipt. **Allowable Values:** 32 bytes | | what\_is\_the\_currency\_on\_the\_cardholders\_receipt string Conditionally required | The currency on the cardholder's receipt. **Allowable Values:** A valid currency code. | | is\_the\_dispute\_due\_to\_the\_difference\_between\_quoted\_price\_and\_actual\_charges\_made\_by\_the\_merchant boolean Conditionally required | Indicates whether the dispute appeared due to the difference between quoted price and actual charges made by the merchant. **Allowable Values:** `true`, `false` | ## Response body | Fields | Description | | - | - | | token string Returned | Unique identifier of the dispute case. **Allowable Values:** 36 char max | | type string Returned | Dispute case type. **Allowable Values:** `DISPUTE` | | memo string Returned | Free-form comments about the dispute. **Allowable Values:** 512 char max | | program\_short\_code string Returned | Indicates which program the case belongs to. **Allowable Values:** 10 char max | | user\_token string Returned | Unique identifier of the cardholder who made the original transaction. **Allowable Values:** 36 char max | | business\_token string Returned | Unique identifier of the business involved in the dispute case. **Allowable Values:** 36 char max | | state string Returned | Indicates the current case state. **Allowable Values:** `OPEN`, `OPEN_WITH_ACTION_REQUIRED`, `READY`, `CHARGEBACK_INITIATED`, `CLOSED` | | assignee string Returned | Indicates who is working on the case. **Allowable Values:** 255 char max | | salesforce\_ticket\_id string Optional | Identifier of the Salesforce ticket. **Allowable Values:** 255 char max | | type\_change\_time datetime Optional | Date and time when the dispute case type was changed. **Allowable Values:** Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ | | dispute\_details object Returned | Details of the dispute case. **Allowable Values:** See [The dispute\_details\_response object](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-cases-pulse/list-dispute-cases-pulse.md#_the_dispute_details_response_object) table. | | created\_time datetime Returned | Date and time when the dispute case was created. **Allowable Values:** Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ | | updated\_time datetime Returned | Date and time when the dispute case was last updated. **Allowable Values:** Format: yyyy-MM-dd'T'HH:mm:ss.SSSZ | ## Sample request body ```json JSON lines wrap theme={null} { "dispute_details": { "dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT", "dispute_amount": 90.00, "original_transaction_token": "b0c7a19e-e172-4c55-9af3-aad89c339b78", "cardholder_contact_date": "2025-02-03T00:00:00Z" }, "type": "DISPUTE" } ``` ## Sample response body ```json JSON lines wrap theme={null} { "created_time": "2025-03-02T19:28:56Z", "last_modified_time": "2025-03-02T19:28:56Z", "token": "deqa-55349", "type": "DISPUTE", "user_token": "a5dc8fd4-c428-469c-ab6a-c2b2852771bc", "state": "OPEN", "dispute_details": { "original_transaction_token": "b0c7a19e-e172-4c55-9af3-aad89c339b78", "original_transaction_type": "authorization.clearing", "dispute_amount": 90.00, "currency_code": "GBP", "dispute_reason": "NOT_AUTHORIZED_CARD_ABSENT", "network": "PULSE", "card_token": "8f49f6e5-ced2-4324-b930-829b3305f155", "provisional_credit_granted": false, "acquirer_fee": 0.0000, "associated_transaction_selection_required": false } } ``` ## Related topics - [Create dispute case](https://www.marqeta.com/docs/core-api/disputes-mastercard/dispute-cases-mastercard/create-dispute-case-mastercard.md) - [Create dispute case transition](https://www.marqeta.com/docs/core-api/disputes-pulse/dispute-case-transitions-pulse/create-dispute-case-transition-pulse.md) - [Create dispute case action](https://www.marqeta.com/docs/core-api/disputes-pulse/create-dispute-case-action-pulse.md) - [Create dispute case content](https://www.marqeta.com/docs/core-api/disputes-visa/dispute-case-content-visa/create-dispute-case-content-visa.md) - [Dispute Cases (Mastercard) Overview](https://www.marqeta.com/docs/core-api/disputes-mastercard/dispute-cases-mastercard.md)