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 do not want to defend the dispute, accept the dispute.
3. Upload all relevant defense material for the dispute.
   • Optional: Before defending the dispute, it is possible to delete defense documents that you submitted previously.
4. Submit your complete defense to the scheme and defend the dispute.

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

To test your integration, you can simulate chargeback scenarios by submitting dispute reasons. For more details, see test a chargeback scenario.

Requirements

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

1. Understand the disputes process. See Understanding disputes for a high-level overview of the flow, and 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 are using an existing API credential. You need it for API calls you make to the Adyen payments platform. If you do not have the API key, contact your Admin user.
6. Check if your API credential has the API dispute management role. If you do not 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, see 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.

   Make a POST request to the /retrieveApplicableDefenseReasons endpoint.

   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.

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 for more information on how to build a compelling disputes package. See the Disputes API reference for an overview of common defense reason codes and defense document type codes.

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 request 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. 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), and 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.

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

   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 for a list of possible errors.

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.

   Make a POST request to the /deleteDisputeDefenseDocument endpoint.

   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 for a list of possible errors.

2. Repeat step 3 to upload new defense documents.

Step 4: Defend the dispute

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.

   Make a POST request to the /defendDispute endpoint.

   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 for a list of possible errors.

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

See also