Are you looking for test card numbers?

Would you like to contact support?

Risk-management icon

Disputes API

Automate your process of handling disputes with our Disputes API.

Our Disputes API lets you automate the dispute handling process so you can respond to disputes as soon as they are initiated.

When using the Disputes API, these are the things you need to do:

  1. Handle dispute webhooks. Use the event codes to determine which stage the dispute is in.
  2. Retrieve dispute information to understand how you can defend the dispute.
    • If you want to defend the dispute, continue with step 3.
    • Optional: If you don't want to defend the dispute, accept the dispute.
  3. Upload all relevant defense material for the dispute.
  4. Submit your complete defense to the scheme and defend the dispute.

For a list of endpoints and parameters, see Disputes API reference.

To test your integration, you can simulate chargeback scenarios by submitting dispute reasons. Refer to Test a chargeback scenario for more details.

If you would like to handle disputes manually instead, you can manage disputes through your Customer Area.

Before you begin

Before starting your Disputes API integration, make sure that you:

  1. Understand the disputes process. Refer to Understanding disputes for a high level flow, and to Chargeback guidelines for scheme-specific information.
  2. Know the scenarios when Adyen automatically handles disputes on your behalf.
  3. Set up your server to receive webhooks. We inform you of dispute status updates through webhooks.
  4. Learn about the types of dispute webhooks that you can receive.
  5. Have a copy of the API key if you're using an existing API credential. You need it for API calls you make to the Adyen payments platform. If you don't have the API key, contact your Admin user.
  6. Check if your API credential has the API dispute management role. If you don't have the role yet, ask your Admin user to enable this. If the role is not available for your Admin user, contact our Support Team.

Step 1: Handle dispute webhooks

Adyen notifies you of any disputed payment event. For a list of all events related to disputes, refer to Dispute webhooks.

  • When a shopper starts a dispute process with their issuer, you receive any of the following event codes:

    • 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  – 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. The chargeback debit usually occurs a few days after you receive this webhook.

After you receive webhooks with any of the event codes above, start the disputes process using the Disputes API.

Step 2: 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.
    • merchantAccountCode: The merchant account the dispute was placed through.

    For JSON requests, make a POST to /retrieveApplicableDefenseReasons endpoint.

    {
    "disputePspReference": "9913486733050065",
    "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <retrieveApplicableDefenseReasons xmlns="http://dispute.services.adyen.com">
      <request>
        <disputePspReference>9913486733050065</disputePspReference>
        <merchantAccountCode>YOUR_MERCHANT_ACCOUNT</merchantAccountCode>
      </request>
    </retrieveApplicableDefenseReasons>
  </soap:Body>
</soap:Envelope>

    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.

    {
    "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
    }
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
    <soap:Body>
        <ns0:retrieveApplicableDefenseReasonsResponse>
            <ns0:response>
                <ns0:defenseReasons>
                    <ns0:DefenseReason>
                        <ns0:defenseDocumentTypes>
                            <ns0:DefenseDocumentType>
                                <ns0:available>false</ns0:available>
                                <ns0:defenseDocumentTypeCode>TIDorInvoice</ns0:defenseDocumentTypeCode>
                                <ns0:requirementLevel>Optional</ns0:requirementLevel>
                            </ns0:DefenseDocumentType>
                            <ns0:DefenseDocumentType>
                                <ns0:available>false</ns0:available>
                                <ns0:defenseDocumentTypeCode>DefenseMaterial</ns0:defenseDocumentTypeCode>
                                <ns0:requirementLevel>Required</ns0:requirementLevel>
                            </ns0:DefenseDocumentType>
                            <ns0:DefenseDocumentType>
                                <ns0:available>true</ns0:available>
                                <ns0:defenseDocumentTypeCode>AlternativeDefenseMaterial</ns0:defenseDocumentTypeCode>
                                <ns0:requirementLevel>AlternativeRequired</ns0:requirementLevel>
                            </ns0:DefenseDocumentType>
                        </ns0:defenseDocumentTypes>
                        <ns0:defenseReasonCode>SupplyDefenseMaterial</ns0:defenseReasonCode>
                        <ns0:satisfied>true</ns0:satisfied>
                    </ns0:DefenseReason>
                </ns0:defenseReasons>
                <ns0:disputeServiceResult>
                    <ns0:success>true</ns0:success>
                </ns0:disputeServiceResult>
            </ns0:response>
        </ns0:retrieveApplicableDefenseReasonsResponse>
    </soap:Body>
</soap:Envelope>

    For information on available fields, including a mapping of defenseReasonCode and defenseDocumentTypeCode values, refer to DefenseReasonsResponse.


  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 our defense requirements page for more information on how to build a compelling disputes package.

    If you would like to just submit a generic dispute document in response to all chargebacks, contact our Support Team to enable the AlternativeDefenseMaterial type on your account.

    To defend the dispute, continue with step 3.

Optional step: 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 to the /acceptDispute endpoint, providing the disputePspReference and the merchantAccountCode.

Step 3: 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 set by schemes.

    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.


  1. 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.

    For JSON requests, make a POST to /supplyDefenseDocument endpoint.

    {
    "defenseDocuments": [
        {
            "content": "JVBERi0xLjMKJcTl8uXrp...",
            "contentType": "application/pdf",
            "defenseDocumentTypeCode": "MerchandiseDescription"
        }
    ],
    "disputePspReference": "9913486733050065",
    "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <supplyDefenseDocument xmlns="http://dispute.services.adyen.com">
      <request>
        <defenseDocuments>
          <DefenseDocument>
            <content>JVBERi0xLjMKJcTl8uXrp...</content>
            <contentType>application/pdf</contentType>
            <defenseDocumentTypeCode>MerchandiseDescription</defenseDocumentTypeCode>
          </DefenseDocument>
        </defenseDocuments>
        <disputePspReference>9913486733050065</disputePspReference>
        <merchantAccountCode>YOUR_MERCHANT_ACCOUNT</merchantAccountCode>
      </request>
    </supplyDefenseDocument>
  </soap:Body>
</soap:Envelope>

    The response contains the success field, a boolean that indicates if the request was successful.

    {
    "disputeServiceResult": {
        "success": true
    }
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
  <soap:Body>
    <ns0:supplyDefenseDocumentResponse>
      <ns0:response>
        <ns0:disputeServiceResult>
          <ns0:success>true</ns0:success>
        </ns0:disputeServiceResult>
      </ns0:response>
    </ns0:supplyDefenseDocumentResponse>
  </soap:Body>
</soap:Envelope>

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 API request in step 4.

Optional step: Delete dispute defense documents

If the defense documents you provided in step 3 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.

    For JSON requests, make a POST to /deleteDisputeDefenseDocument endpoint.

    {
    "disputePspReference": "9913486733050065",
    "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT",
    "defenseDocumentType": "MerchandiseDescription"
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <deleteDisputeDefenseDocument xmlns="http://dispute.services.adyen.com">
      <request>
        <disputePspReference>9913486733050065</disputePspReference>
        <merchantAccountCode>YOUR_MERCHANT_ACCOUNT</merchantAccountCode>
        <defenseDocumentType>MerchandiseDescription</defenseDocumentType>
      </request>
    </deleteDisputeDefenseDocument>
  </soap:Body>
</soap:Envelope>

    The response contains the success field, a boolean that indicates if the request was successful.

    {
    "disputeServiceResult": {
        "success": true
    }
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.or/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
  <soap:Body>
    <ns0:deleteDefenseDocumentResponse>
      <ns0:response>
        <ns0:disputeServiceResult>
          <ns0:success>true</ns0:success>
        </ns0:disputeServiceResult>
      </ns0:response>
    </ns0:deleteDefenseDocumentResponse>
  </soap:Body>
</soap:Envelope>

  2. Repeat step 3 to upload new defense documents.

Step 4: Defend 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.
    • merchantAccountCode: The merchant account the dispute was placed through.

    For JSON requests, make a POST to /defendDispute endpoint.

    {
    "disputePspReference": "9913486733050065",
    "defenseReasonCode": "SupplyDefenseMaterial",
    "merchantAccountCode": "YOUR_MERCHANT_ACCOUNT"
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <soap:Body>
    <defendDispute xmlns="http://dispute.services.adyen.com">
      <request>
        <defenseReasonCode>SupplyDefenseMaterial</defenseReasonCode>
        <disputePspReference>9913486733050081</disputePspReference>
        <merchantAccountCode>YOUR_MERCHANT_ACCOUNT</merchantAccountCode>
      </request>
    </defendDispute>
  </soap:Body>
</soap:Envelope>

    The response contains the success field, a boolean that indicates if the request was successful.

    {
    "disputeServiceResult": {
        "success": true
    }
}
    <?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:ns0="http://dispute.services.adyen.com">
  <soap:Body>
    <ns0:supplyDefenseDocumentResponse>
      <ns0:response>
        <ns0:disputeServiceResult>
          <ns0:success>true</ns0:success>
        </ns0:disputeServiceResult>
      </ns0:response>
    </ns0:supplyDefenseDocumentResponse>
  </soap:Body>
</soap:Envelope>

  2. Keep track of the status of the dispute through the dispute webhooks that you receive.

See also