# Disputes > How Moov handles card disputes and chargebacks, which webhooks notify you, and how to accept or challenge disputes with evidence via the API or Dashboard. > AI agents: search and read all Moov docs with the docs MCP server at https://docs.moov.io/mcp (no API key). Setup: https://docs.moov.io/guides/developer-tools/mcp-ai/docs-mcp/index.md When a cardholder disputes a card payment, Moov debits the merchant's wallet and notifies you. This page covers the dispute lifecycle, response deadlines, and how to accept or challenge a dispute. A dispute occurs when a cardholder formally questions the validity of a payment by raising a complaint to their card issuer. A dispute can be automatically resolved if a merchant utilizes a pre-dispute service. Otherwise, the card issuer will process a chargeback, temporarily reversing the payment for the duration of the dispute. Moov currently supports RDR (Visa Rapid Dispute Resolution) decisioned pre-disputes and chargebacks from all card networks. ## How Moov processes chargebacks Moov engages directly with the card networks and communicates dispute details to you via API and Dashboard. Moov’s customers must pull dispute data and pass it along to their merchants on an ongoing basis. The chargeback amount can be either a portion of the original transfer, or the full amount of a transfer. Once we receive chargeback details from the card network, we process the chargeback by debiting the merchant’s Moov wallet. ## Get notified of disputes As the main account holder, you are responsible for notifying impacted merchants of any incoming disputes. You can receive notifications on disputes through the `dispute.created` and `dispute.updated` [webhook events](/guides/webhooks/webhook-events/index.md#disputes). These events tell you when a dispute is created, updated, and completed. The `dispute.updated` webhook will generate if there is a change to `status` or `phase`. Alternatively, you can use the disputes list `GET` [endpoint](/api/money-movement/disputes/list/index.md) to pull a list of disputes on a recurring schedule. Note that even if a transfer has a dispute, its overall transfer status will remain `completed`. ## View dispute information If a transfer has been disputed, you can see information about the dispute on the transfer object for the original `transferID` in question. A cardholder can dispute a charge for various reasons. The following response fields provide helpful information about a dispute and will allow merchants to compile the appropriate compelling evidence: | Field | Description | |----------------------------|------------------------------------------------------------------------------------| | `networkReasonCode` | The card network’s category for the dispute. Codes may differ between card brands. | | `networkReasonDescription` | Card network categorization details of the dispute. | | `phase` | The current phase of a dispute. | | `status` | The current status of a dispute. | The following is an example of a dispute response: ```json { "amount": { "currency": "USD", "value": 1204 }, "createdOn": "2023-08-24T14:15:22Z", "disputeID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43", "merchantAccountID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43", "networkReasonCode": "string", "networkReasonDescription": "string", "phase": "chargeback", "respondBy": "2023-08-24T14:15:22Z", "status": "response-needed", "transfer": { "transferID": "ec7e1848-dc80-4ab0-8827-dd7fc0737b43" } } ``` ### Phases See the `phase` field in either of the dispute `GET` [endpoint](/api/money-movement/disputes/index.md) responses to see the current phase of a dispute. Disputes can have the following phases (note some phases currently only apply to specific card networks): | Phase | Description | |---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | `pre-dispute` | Visa only. Moov supports Visa’s Rapid Dispute Resolution integration which helps merchants auto-resolve pre-disputes and avoids potential chargebacks. | | `inquiry` | American Express only. Preliminary phase before a formal chargeback is created. | | `chargeback` | Transfer is actively being disputed. Moov wallet is debited immediately. | | `unknown` | There was a processing error. | American Express may send an inquiry to a merchant to request more information regarding a chargeback. This is a preliminary phase before a formal chargeback is created - no funds are debited from the merchant’s Moov wallet. In this phase, merchants can either accept liability by refunding the transfer, or prevent a chargeback by providing sufficient information. ### Dispute statuses See the `status` field in either of the dispute `GET` [endpoint](/api/money-movement/disputes/index.md) responses to see the current status of a dispute. Disputes can have the following statuses: | Status | Description | |-------------------|-------------------------------------------------------------------------------------------------------------------------| | `resolved` | No more action is required on these transactions. | | `response-needed` | Default response for all unresolved disputes. The merchant needs to communicate to Moov how they would like to proceed. | | `under-review` | Evidence has been submitted for a dispute and is being reviewed by the card network. | | `accepted` | The merchant has accepted liability for the dispute. | | `closed` | The issuer has reversed the chargeback, or evidence provided for the inquiry was sufficient. | | `won` | The evidence was compelling and the dispute was won. Funds have been credited back to the merchant wallet. | | `lost` | The evidence was not compelling and the dispute was lost. | | `expired` | The due date for a [response](#respond-to-disputes) to the chargeback or inquiry has passed. | Dispute information is also available in the Dashboard under **Transfers > Disputes**. See [In the Dashboard](#in-the-dashboard). ## Respond to disputes If a merchant receives a chargeback, they can either **accept liability** or **challenge the chargeback**. Use the endpoints in the following sections to address specific stages of the dispute. If a merchant does not respond to a chargeback by the `respondBy` date, the chargeback expires and the merchant automatically accepts liability. Once evidence is submitted, the merchant will need to wait for the card network's final decision. If the evidence is sufficient, the dispute status will update to `won` and funds will be credited. If the evidence is insufficient, the dispute status will update to `lost`. Use the tabs below to view dispute flow diagrams based on phase. **Phase: Chargeback** A dispute with `phase: chargeback` will update to `status: response-needed` and the merchant is required to accept or deny liability. If the merchant denies liability, evidence will need to be submitted and the merchant will either win or lose the dispute. The dispute can also be closed by the issuer. ![](./images/dispute-chargeback-light.png) **Phase: Pre-dispute (Visa only)** A dispute with `phase: pre-dispute` can be resolved through Visa's Rapid Dispute Resolution, or closed by the issuer. ![](./images/dispute-pre-light.png) **Phase: Inquiry (Amex only)** A dispute with `phase: inquiry` is in a preliminary chargeback phase and evidence can be submitted if the merchant denies liability. If the evidence submitted in the inquiry phase is deemed insufficient, the dispute will update to `phase: chargeback`. The liability and evidence process will start over and the merchant will either win or lose the dispute. The dispute can also be closed by the issuer. ![](./images/dispute-inquiry-light.png) ### Response deadlines Responses to disputes are due to Moov by the `respondBy` date and vary by card brand: | Card brand | Dispute respondBy | |------------|-------------------| | Visa | 6 calendar days | | Mastercard | 14 calendar days | | Discover | 14 calendar days | | Amex | 10 calendar days | If no response is submitted before the deadline, we’ll accept the dispute on your behalf and the disputed amount will not be recovered. > **Note:** It's possible to receive an American Express chargeback without an inquiry phase. [View dispute information](#view-dispute-information) for details about dispute phases. ### Accept dispute Accepting liability on a chargeback means the merchant will not contest the dispute and will accept the permanent return of the funds to the cardholder. This is final action and cannot be undone. If the phase is `chargeback` and the status is `response-needed`, the dispute can be accepted using the dispute `POST` [endpoint](/api/money-movement/disputes/post/index.md). If the dispute is successful, the status will update to `accepted`. When a dispute is accepted, there is no additional movement of funds. The funds debit when the chargeback is received. If the phase is `inquiry` and the status is `response-needed`, the dispute can be accepted by [refunding](/api/money-movement/refunds/cancel/index.md) the transfer. ### Challenge dispute Challenging a chargeback requires gathering and submitting compelling evidence. Evidence can only be submitted once per dispute. #### Upload evidence Evidence must be uploaded before the `respondBy` due date. Evidence can only be uploaded if the phase is `chargeback` or `inquiry` and the status is `response-needed`. Evidence must be tagged with one of the following evidence types listed below and adhere to [file size and format](#file-size--format-requirements) guidelines. | Evidence type | Description | |--------------------------|------------------------------------------------------------------------------------------------------| | `receipt` | Proof of purchase notifying the customer about the charge. | | `proof-of-delivery` | Confirmation that the goods or services were delivered to the customer. | | `cancelation-policy` | Cancellation or refund policy as it was provided to the customer. | | `terms-of-service` | Terms of service policy as it was provided to the customer. | | `customer-communication` | Acknowledgement from cardholder withdrawing the dispute or email evidence that dispute was resolved. | | `cover-letter` | Summary of the challenge (Moov can provide guidelines or a template if requested). | | `generic-evidence` | Additional evidence that is outside the definition of the other evidence type categories. | There are two endpoints to upload evidence, depending on the evidence format. For example, you can upload a `cover-letter` as text and a `receipt` as a file. - File `POST` [endpoint](/api/money-movement/disputes/post-file/index.md) - Text `POST` [endpoint](/api/money-movement/disputes/post-text/index.md) After uploading all evidence, it must be [submitted](#submit-evidence). #### Update evidence Evidence can only be updated if the dispute status is `response-needed`. Use the dispute `PATCH` [endpoint](/api/money-movement/disputes/patch/index.md) to update evidence. #### Delete evidence Use the dispute `DELETE` [endpoint](/api/money-movement/disputes/delete/index.md) to delete a specific piece of evidence. #### Submit evidence **Evidence can only be submitted once per dispute** -- do not submit until everything is finalized. Evidence can only be submitted if the phase is `chargeback` or `inquiry` and the status is `response-needed`. Evidence must be submitted before the `respondBy` due date and cannot be submitted with an empty evidence body. Once evidence is successfully submitted, the status will update to `under-review`. Use the dispute `POST` [endpoint](/api/money-movement/disputes/post-evidence/index.md) to submit evidence. #### Retrieve evidence Use the dispute `GET` endpoints to retrieve evidence metadata for a specific dispute. - List all dispute evidence `GET` [endpoint](/api/money-movement/disputes/list-evidence/index.md) - Retrieve a specific piece of dispute evidence `GET` [endpoint](/api/money-movement/disputes/get-evidence/index.md) The following is an example of retrieved evidence metadata: ```json [ { "evidenceID": "9b56817a-0f9f-4756-86a5-83cff8426d35", "disputeID": "a362c415-1ff3-445a-843a-2f6cf0e031ee", "createdOn": "2022-10-24T00:00:00Z", "evidenceType": "receipt", "filename": "receipt.jpg", "size": 467, "mimeType": "image/jpeg" }, { "evidenceID": "4e677336-464c-4a0c-b125-65aa2422bad3", "disputeID": "a362c415-1ff3-445a-843a-2f6cf0e031ee", "createdOn": "2022-10-24T00:00:00Z", "evidenceType": "proof-of-delivery", "filename": "screenshot.jpg", "size": 723, "mimeType": "image/jpeg" } ] ``` ### File size & format requirements Moov requires supporting documents to fit within the following type, size, and naming specification parameters: | Type | Size | |------|---------------------------| | PDF | File size maximum is 4 MB | | JPG | File size maximum is 4 MB | | TIFF | File size maximum is 4 MB | **Naming specifications** for all documents are as follows: - 16 or fewer alphanumeric characters - No special characters - Must not contain sensitive info (such as PANs) ## In the Dashboard Navigate to **Transfers > Disputes** in the Dashboard. You can view, accept, challenge, delete, and update disputes, as well as view, upload, and update dispute evidence. The main disputes table lists the amount, status and phase, reason code, merchant account, respond by date, and disputed date. ![Dispute list in the Dashboard](images/disputes-view.png) You can filter disputes by status, phase, respond by, or disputed dates. You can also search disputes using the dispute ID or transfer ID. ![Filter disputes in the Dashboard](images/disputes-filter.png) ### Dispute details and evidence Click a dispute to go to the transfer details page, where you can view additional information such as the entire transfer timeline and the dispute and transfer IDs. From here you can accept the dispute and start the refund process, or challenge the dispute by submitting evidence. ![Dispute details in the Dashboard](images/dispute-details.png) If you challenge the dispute, upload and submit evidence such as proof of purchase or terms of service within the transfer details page. Responses are due by the `Respond by` date, which varies by card brand. See [response deadlines](#response-deadlines). [*Video: submit dispute evidence*](https://docs.moov.io/guides/shared-images/submit-dispute-evidence.mp4) ### Accept a dispute in the Dashboard To accept the dispute from the transfer details page, click the **Refund** button and follow the [reversal or refund](/guides/money-movement/overview/index.md#refund-reverse-or-cancel-a-transfer) procedure. [*Video: accept dispute*](https://docs.moov.io/guides/shared-images/accept-dispute.mp4)