---
title: "Manage disputes with the Disputes API"
description: "Automate your process of handling disputes using our Defend Disputes API."
url: "https://docs.adyen.com/risk-management/disputes-api"
source_url: "https://docs.adyen.com/risk-management/disputes-api.md"
canonical: "https://docs.adyen.com/risk-management/disputes-api"
last_modified: "2020-05-27T10:40:00+02:00"
language: "en"
---

# Manage disputes with the Disputes API

Automate your process of handling disputes using our Defend Disputes API.

[View source](/risk-management/disputes-api.md)

Our Defend Disputes API, or Disputes API in short, lets you automate the dispute handling process so you can respond to disputes as soon as they are initiated. You can retrieve dispute information, defend or accept disputes, and upload defense documents.

If you want to handle disputes manually instead, you can manage disputes through the [Customer Area](/risk-management/manage-disputes).

## Requirements

Before you begin, take into account the following requirements and limitations.

| Requirement                                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type**                                           | Make sure that you have built an [online payments integration](/online-payments/build-your-integration/).                                                                                                                                                                                                                                                                                                                                      |
| **[API credentials](/development-resources/api-credentials/)** | Make sure that you have an API credential with an API key and the **API dispute management** role. If the role is not available for your admin user, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other).                                                                                                                                                                                           |
|                                                                |                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **[Webhooks](/development-resources/webhooks)**                | To follow disputes using webhooks, subscribe to the **Standard webhook** and [enable](/risk-management/disputes-api/dispute-notifications#dispute-webhooks-enable) dispute events.                                                                                                                                                                                                                                                             |
| **Limitations**                                                | Not all dispute types can be defended.                                                                                                                                                                                                                                                                                                                                                                                                         |
| **Setup steps**                                                | Before you begin, make sure that you:- Understand the general [dispute flow](/risk-management/understanding-disputes/dispute-process-and-flow/).
- Review the [chargeback guidelines](/risk-management/chargeback-guidelines) for specific card schemes and other payment methods that you use.
- Know the scenarios when Adyen [automatically handles disputes](/risk-management/manage-disputes#adyen-auto-defense-disputes) on your behalf. |

## How it works

The overall process is as follows:

1. [Handle dispute webhooks](#handle-dispute-notifications). Use the webhook messages and event codes to determine the dispute status.

2. [Retrieve dispute information](#retrieve-dispute-information) to understand how you can defend the dispute.

   * If you want to defend the dispute, gather and upload defense materials.
   * **Optional**: If you do not want to defend the dispute, [accept the dispute](#accept-dispute).

3. [Upload](#supply-dispute-defense-documents) all relevant defense material for the dispute.
   * **Optional**: Before defending the dispute, it is possible to [delete defense documents](#delete-dispute-defense-documents) that you uploaded previously.

4. Submit your complete defense to the scheme and [defend the dispute](#defend-dispute).

For a list of endpoints and parameters, see [Disputes API](https://docs.adyen.com/api-explorer/Disputes/latest/overview). To test your integration, you can [simulate different chargeback scenarios](/risk-management/disputes-api/test-applicable-dispute-reasons).

5. **Optional**: [Handle pre-arbitration cases](#pre-arbitration-disputes-api).\
   For some dispute flows, the issuer can open a pre-arbitration case if they decline your defense. When you are eligible, and the dispute flow supports it, you can accept or decline the pre-arbitration case yourself. This requires additional configuration and approval from Adyen. Reach out to our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other) or your Adyen contact for more details.

## Handle dispute webhooks

Adyen sends you a webhook message when a payment is disputed. For a list of all event types related to disputes, see [Dispute webhooks](/risk-management/disputes-api/dispute-notifications/).

* When a shopper starts a dispute process with their issuer, you receive a webhook message when any of the following events happen:

  * [**REQUEST\_FOR\_INFORMATION** ](/risk-management/disputes-api/dispute-notifications#request_for_information) – Information requested for this payment. At this stage, no money is withdrawn from your account. However, if you do not respond in a timely manner, a chargeback may take place, and money may be withdrawn from your account. Providing sufficient evidence at this state may prevent a dispute from ever reaching the chargeback state.

  * [**NOTIFICATION\_OF\_CHARGEBACK** ](/risk-management/disputes-api/dispute-notifications#notification_of_chargeback) – A chargeback is incoming and can be defended. This is your starting point for the defense, and marks the start of the defense period. You can now start your defense. To defend the dispute, you need to [upload the defense documentation](#supply-dispute-defense-documents). The chargeback debit usually occurs a few days after you receive this webhook message.

After you receive a webhook message with any of these event codes, start the disputes process using the Disputes API.

## Retrieve dispute information

To retrieve information about the dispute, you retrieve the applicable defense reasons and the required defense document types.

1. To get a list of applicable defense reasons and required document types, provide the following:

   * `disputePspReference`: The `pspReference` you received in the webhook message.
   * `merchantAccountCode`: The merchant account the dispute was placed through.

   Make a POST request to the [/retrieveApplicableDefenseReasons](https://docs.adyen.com/api-explorer/Disputes/latest/post/retrieveApplicableDefenseReasons) endpoint.

   **Example /retrieveApplicableDefenseReasons request**

   ```json
   {
   	  "disputePspReference": "FKSPNCQ8HXSKGK82",
   	  "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
   }
   ```

   The response contains a list of the available defense reasons and corresponding document types that can be used to defend the dispute, specified by scheme regulations.

   The following shows an example response when you have enabled `AlternativeDefenseMaterial` on your account. This lets you submit a generic dispute document in response to all chargebacks. To enable this option, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other).

   **Example /retrieveApplicableDefenseReasons response**

   ```json
   {
       "defenseReasons": [
           {
             "defenseDocumentTypes": [
                 {
                   "available": false,
                   "defenseDocumentTypeCode": "TIDorInvoice",
                   "requirementLevel": "Optional"
                 },
                 {
                   "available": false,
                   "defenseDocumentTypeCode": "DefenseMaterial",
                   "requirementLevel": "Required"
                 },
                 {
                   "available": false,
                   "defenseDocumentTypeCode": "AlternativeDefenseMaterial",
                   "requirementLevel": "AlternativeRequired"
                 }
             ],
             "defenseReasonCode": "SupplyDefenseMaterial",
             "satisfied": false
           }
       ],
       "disputeServiceResult": {
         "success": true
       }
   }
   ```

2) Get the `defenseReasonCode` and `defenseDocumentTypeCode` from the response. Use both parameters to determine the type of document that you need to construct an evidence package to defend the dispute. Review the [defense requirements](/risk-management/understanding-disputes/dispute-reason-codes/#defense_requirements) for more information on how to build a compelling disputes package. See the [Disputes API reference](/risk-management/disputes-api/disputes-api-reference/) for an overview of common [defense reason codes](/risk-management/disputes-api/disputes-api-reference/#dispute-defense-reason-code) and [defense document type codes](/risk-management/disputes-api/disputes-api-reference/#dispute-defense-document-type-code).

To defend the dispute, [gather and upload defense materials.](#supply-dispute-defense-documents).

## Optional: Accept the dispute

If you choose not to defend the dispute after retrieving the dispute details, you can accept it. To do so, make a POST request to the [/acceptDispute](https://docs.adyen.com/api-explorer/Disputes/latest/post/acceptDispute) endpoint, providing the `disputePspReference` and the `merchantAccountCode`.

## Upload dispute defense documents

After you identify which document types to include in your evidence package, you need to:\
[]()

1. Check if your documents comply with the following [general guidelines and restrictions](/risk-management/understanding-disputes/dispute-reason-codes/#defense_requirements) set by schemes. Make sure that your defense documents do not contain sensitive data. Adyen will refuse defense material that contains data such as copies of passports, social security numbers, tax records, unrelated legal documents, Primary Account Numbers ([PAN](/get-started-with-adyen/adyen-glossary/#card-number-pan)), and [sensitive authentication data](/get-started-with-adyen/adyen-glossary/#sensitive-authentication-data).

   You can supply defense documents in the following file formats:

   * JPG (maximum file size 10 MB)
   * TIFF (maximum file size 10 MB)
   * PDF (maximum file size 2 MB)

   Specific requirements:

   * For Diners and Discover, the maximum file size is 3 MB.
   * For Mastercard, the maximum number of pages for a chargeback defense document is 19.
   * Klarna only accepts defense documents in PDF format.
   * For Mexico domestic chargeback defense documents, the maximum file size is 800 KB.
   * For STAR, the maximum file size for JPG and TIFF formats is 5 MB.
   * The maximum number of pages for an RFI defense document is 4.

2) To upload defense documents, provide the following:

   * `defenseDocuments`: An array of the defense documents.

   * `content`: The binary content of the document in a Base64 string.

   * `contentType`: The content type of the document. This can be one of:

     * **image/jpg**
     * **image/jpeg**
     * **image/tiff**
     * **application/pdf**

   * `defenseDocumentTypeCode`: The corresponding document type code of the document.

   * `disputePspReference`: The `pspReference` you received in the webhook.

   * `merchantAccountCode`: The merchant account the dispute was placed through.

   Make a POST request to the [/supplyDefenseDocument](https://docs.adyen.com/api-explorer/Disputes/latest/post/supplyDefenseDocument) endpoint.

   **Example /supplyDefenseDocument request**

   ```json
   {
       "defenseDocuments": [
           {
               "content": "JVBERi0xLjMKJcTl8uXrp...",
               "contentType": "application/pdf",
               "defenseDocumentTypeCode": "MerchandiseDescription"
           }
       ],
       "disputePspReference": "MLSPNCQ8HXSKGK82",
       "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
   }
   ```

   The response contains the `success` field, a boolean that indicates if the request was successful. If the request fails, the response also contains an `errorMessage` field. See [Disputes API reference](/risk-management/disputes-api/disputes-api-reference/) for a list of possible errors.

After you finish this step, the documents are not automatically submitted to the issuer. The documents will only be submitted after you send the final [defend dispute](#defend-dispute) API request.

### Optional: Delete dispute defense documents

If the defense documents you uploaded are incomplete or are not compelling enough, you can still delete the documents and re-upload new defense material.

1. To delete defense material, provide the following:

   * `defenseDocumentType`: The defense document type to delete.
   * `disputePspReference`: The `pspReference` you received in the webhook.
   * `merchantAccountCode`: The merchant account the dispute was placed through.

   Make a POST request to the [/deleteDisputeDefenseDocument](https://docs.adyen.com/api-explorer/Disputes/latest/post/deleteDisputeDefenseDocument) endpoint.

   **Example /deleteDisputeDefenseDocument request**

   ```json
   {
     "defenseDocumentType": "MerchandiseDescription",
     "disputePspReference": "MLSPNCQ8HXSKGK82",
     "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
   }
   ```

   The response contains the `success` field, a boolean that indicates if the request was successful. If the request fails, the response also contains an `errorMessage` field. See [Disputes API reference](/risk-management/disputes-api/disputes-api-reference/) for a list of possible errors.

2. [Upload](#supply-dispute-defense-documents) new defense documents.

## Defend the dispute

This is the final step in the disputes process that requires action from you. After you defend the dispute, you can no longer supply additional information.

1. When you are ready to submit your complete defense to the scheme, provide the following:

   * `defenseReasonCode`: Code identifying the defense reason.
   * `disputePspReference`: The `pspReference` you received in the webhook message.
   * `merchantAccountCode`: The merchant account the dispute was placed through.

   Make a POST request to the [/defendDispute](https://docs.adyen.com/api-explorer/Disputes/latest/post/defendDispute) endpoint.

   **Example /defendDispute request**

   ```json
   {
       "defenseReasonCode": "SupplyDefenseMaterial",
       "disputePspReference": "MLSPNCQ8HXSKGK82",
       "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
   }
   ```

   The response contains the `success` field, a boolean that indicates if the request was successful. If the request fails, the response also contains an `errorMessage` field. See [Disputes API reference](/risk-management/disputes-api/disputes-api-reference/) for a list of possible errors.

2. Keep track of the status of the dispute by listening to the [dispute webhook messages](/risk-management/disputes-api/dispute-notifications) that you receive.

## Optional: Handle pre-arbitration cases

When you are eligible, you can decide to accept or decline a pre-arbitration case.

1. When the issuer opens a pre-arbitration case, you will receive a **PRE\_ARBITRATION\_OPEN** [webhook message](#handle-dispute-notifications).

2. Decide what you want to do:

   1. [Accept](#pre-arbitration-accept) the pre-arbitration case.
   2. [Partially accept](#pre-arbitration-accept-partially) the pre-arbitration case.
   3. [Decline](#pre-arbitration-decline) the pre-arbitration case.

### Accept a pre-arbitration case

When you accept the pre-arbitration case, the dispute is lost, and you receive a second chargeback.

1. When you are ready to accept the pre-arbitration case, provide the following:

   * `disputePspReference`: The `pspReference` of the dispute that you want to accept.
   * `merchantAccountCode`: The merchant account the dispute was placed through.

   Make a POST request to the `/acceptPreArbitration` endpoint.

   **Example /acceptPreArbitration request**

   ```json
   {
       "disputePspReference": "ZC4R4RBFJGXXGN82",
       "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
   }
   ```

2. Listen to the webhook message **PRE\_ARBITRATION\_ACCEPTED**.

3. The dispute is lost. Listen to the webhook message **SECOND\_CHARGEBACK**.

### Partially accept a pre-arbitration case

When you partially accept a pre-arbitration case, you agree to accept a portion of the disputed amount.

1. When you are ready to partially accept the pre-arbitration case, provide the following:

   * `disputePspReference`: The `pspReference` of the dispute.
   * `merchantAccountCode`: The merchant account the dispute was placed through.
   * `amount`: The value and currency that you want to accept. This must be less than the total amount of the disputed transaction.
   * `reason`: A reason or explanation of why you partially accept the case.

   Make a POST request to the `/partialAcceptPreArbitration` endpoint.

   **Example /partialAcceptPreArbitration request**

   ```json
   {
       "disputePspReference": "XB7XNCQ8HXSKGK82",
       "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT",
       "amount": {
           "value": 1000,
           "currency": "EUR"
       },
       "reason": "The reason why you partially accept the pre-arbitration case."
   }
   ```

2. Listen to the webhook message **PRE\_ARBITRATION\_ACCEPTED**.

3. The dispute is partially lost. Listen to the webhook message **SECOND\_CHARGEBACK**.

### Decline a pre-arbitration case

If you decline the pre-arbitration, the case can be sent to scheme arbitration. We recommend that you only decline if you are confident that the chargeback is not valid, and that the defense materials provided during the first chargeback defense were sufficient.

During scheme arbitration, the scheme rules on the chargeback liability based on the information provided throughout chargeback defense timelines. If the scheme rules in favor of the issuer, you can incur a fee of up to USD 600. This fee is added to the second chargeback.

1. When you are ready to decline the pre-arbitration case, provide the following:

   * `disputePspReference`: The `pspReference` of the dispute.
   * `merchantAccountCode`: The merchant account the dispute was placed through.
   * `declineReason`: A reason or explanation of why you decline the case.

   Make a POST request to the `/declinePreArbitration` endpoint.

   **Example /declinePreArbitration request**

   ```json
   {
       "disputePspReference": "WNKH9MC2XJMLNK82",
       "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT",
       "declineReason": "The reason why you decline the pre-arbitration case."
   }
   ```

2. Listen to the webhook message **PRE\_ARBITRATION\_DECLINED**.

3. The case may be sent to scheme arbitration. To know if that happens, listen to the webhook message **SCHEME\_ARBITRATION**. The scheme arbitration process can take several months to complete.

   1. When you get the webhook message **SCHEME\_ARBITRATION\_WON**, you win the dispute, and the money is returned to your account.
   2. When you get the webhook message **SCHEME\_ARBITRATION\_LOST**, you loose the dispute, and a fee is added to the **SECOND\_CHARGEBACK**.

## See also

* [Understanding disputes](/risk-management/understanding-disputes)
* [Dispute webhooks](/risk-management/disputes-api/dispute-notifications)
* [Disputes API reference](/risk-management/disputes-api/disputes-api-reference)
* [Test a chargeback scenario](/risk-management/disputes-api/test-applicable-dispute-reasons)
