# 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 notifications. Use the notification 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.

## 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.
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 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 notification.

After you receive notifications 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 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>
<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: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.

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 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.
• For Klarna, the acceptable format for documents is PDF.

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 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>
<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: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 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>
<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: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 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>
<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>