Search

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 allows you to automate the dispute handling process so you can respond to disputes as soon as they are initiated. You can submit either JSON or XML requests.

When using the Disputes API, you need to:

  1. Handle dispute notifications. Use the notification event codes to determine which stage the dispute is in.
  2. Retrieve applicable defense reasons and corresponding document types that you can use to defend against the dispute.
  3. Upload all relevant defense material for the dispute.
  4. Optional: Before defending the dispute, it is possible to delete defense documents that you submitted previously.
  5. 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 dispute reasons for more details.

If you would like to handle disputes manually instead, upload disputes through our 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 notification webhooks. We inform you of dispute status updates through webhook notifications.
  4. Learn about the types of dispute notifications 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 notifications

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

  • 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 pending and can be defended. To defend the dispute, you need to upload the defense documentation. The chargeback debit usually occurs a few days after you receive this notification.

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

Step 2: Retrieve applicable defense reasons

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

    • disputePspReference: The pspReference you received in the notification.
    • 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 for defending against 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 your 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.

Step 3: Upload dispute defense documents

After you identify which document types to include in your evidence package, you then need to:

  1. Check if your documents comply with the following restrictions set by schemes:

    • By default, acceptable formats for documents are JPG (10MB), TIFF (10MB), or PDF (2MB).
    • For Mastercard, the maximum number of pages for an RFI is 4.
    • For Mastercard, the maximum number of pages for a Chargeback document is 19.
    • For Diners and Discover, the maximum filesize is 3MB.

  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
      • text/plain
      • text/clearing (Maximum of 100 characters)
    • defenseDocumentTypeCode: The corresponding document type code of the document.
    • disputePspReference: The pspReference you received in the notification.
    • 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 5.

Step 4 (Optional): 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 notification.
    • 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 5: 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 notification.
    • 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 notifications that you receive.

See also