Manage disputes with the Disputes API

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.

Requirements

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

How it works

The overall process is as follows:

1. Handle dispute webhooks. Use the webhook messages and event codes to determine the dispute status.
2. 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.
3. Upload all relevant defense material for the dispute.
   • Optional: Before defending the dispute, it is possible to delete defense documents that you uploaded 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 different chargeback scenarios.

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.

• 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  – 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 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 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, gather and upload defense materials..

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 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 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.
   • 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 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: 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 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. Upload new defense documents.

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 message.
   • 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 by listening to the dispute webhook messages that you receive.

See also