{"title":"Manage disputes with the Disputes API","category":"default","creationDate":1575504540,"content":"<p>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.<\/p>\n<p>If you want to handle disputes manually instead, you can manage disputes through the <a href=\"\/risk-management\/manage-disputes\">Customer Area<\/a>.<\/p>\n<h2>Requirements<\/h2>\n<p>Before you begin, take into account the following requirements and limitations.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Requirement<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><strong>Integration type<\/strong><\/td>\n<td style=\"text-align: left;\">Make sure that you have built an <a href=\"\/online-payments\/build-your-integration\/\">online payments integration<\/a>.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong><a href=\"\/development-resources\/api-credentials\/\">API credentials<\/a><\/strong><\/td>\n<td style=\"text-align: left;\">Make sure that you have an API credential with an API key and the <strong>API dispute management<\/strong> role. If the role is not available for your admin user, contact our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a>.<\/td>\n<\/tr>\n<tr>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong><a href=\"\/development-resources\/webhooks\">Webhooks<\/a><\/strong><\/td>\n<td style=\"text-align: left;\">To follow disputes using webhooks, subscribe to the <strong>Standard webhook<\/strong> and <a href=\"\/risk-management\/disputes-api\/dispute-notifications#dispute-webhooks-enable\">enable<\/a> dispute events.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Limitations<\/strong><\/td>\n<td style=\"text-align: left;\">Not all dispute types can be defended.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Setup steps<\/strong><\/td>\n<td style=\"text-align: left;\">Before you begin, make sure that you: <ul><li markdown=\"1\">Understand the general <a href=\"\/risk-management\/understanding-disputes\/dispute-process-and-flow\/\">dispute flow<\/a>.<\/li><li markdown=\"1\">Review the <a href=\"\/risk-management\/chargeback-guidelines\">chargeback guidelines<\/a> for specific card schemes and other payment methods that you use.<\/li><li markdown=\"1\">Know the scenarios when Adyen <a href=\"\/risk-management\/manage-disputes#adyen-auto-defense-disputes\">automatically handles disputes<\/a> on your behalf.<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2>How it works<\/h2>\n<p>The overall process is as follows:<\/p>\n<ol>\n<li><a href=\"#handle-dispute-notifications\">Handle dispute webhooks<\/a>. Use the webhook messages and event codes to determine the dispute status.<\/li>\n<li><a href=\"#retrieve-dispute-information\">Retrieve dispute information<\/a> to understand how you can defend the dispute.\n<ul>\n<li>If you want to defend the dispute, gather and upload defense materials.<\/li>\n<li><strong>Optional<\/strong>: If you do not want to defend the dispute, <a href=\"#accept-dispute\">accept the dispute<\/a>.<\/li>\n<\/ul><\/li>\n<li><a href=\"#supply-dispute-defense-documents\">Upload<\/a> all relevant defense material for the dispute.\n<ul>\n<li><strong>Optional<\/strong>: Before defending the dispute, it is possible to <a href=\"#delete-dispute-defense-documents\">delete defense documents<\/a> that you uploaded previously.<\/li>\n<\/ul><\/li>\n<li>Submit your complete defense to the scheme and <a href=\"#defend-dispute\">defend the dispute<\/a>.<\/li>\n<\/ol>\n<p>For a list of endpoints and parameters, see  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Disputes\/latest\/overview\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">Disputes API<\/a>. To test your integration, you can <a href=\"\/risk-management\/disputes-api\/test-applicable-dispute-reasons\">simulate different chargeback scenarios<\/a>.<\/p>\n<ol start=\"5\">\n<li><strong>Optional<\/strong>: <a href=\"#pre-arbitration-disputes-api\">Handle pre-arbitration cases<\/a>.<br \/>\nFor some dispute flows, the issuer can open a pre-arbitration case if they decline your defense. When you are eligible, and the dispute flow supports it, you can accept or decline the pre-arbitration case yourself. This requires additional configuration and approval from Adyen. Reach out to our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a> or your Adyen contact for more details.<\/li>\n<\/ol>\n<h2 id=\"handle-dispute-notifications\">Handle dispute webhooks<\/h2>\n<p>Adyen sends you a webhook message when a payment is disputed. For a list of all event types related to disputes, see <a href=\"\/risk-management\/disputes-api\/dispute-notifications\/\">Dispute webhooks<\/a>.<\/p>\n<ul>\n<li>\n<p>When a shopper starts a dispute process with their issuer, you receive a webhook message when any of the following events happen:<\/p>\n<ul>\n<li>\n<p><a href=\"\/risk-management\/disputes-api\/dispute-notifications#request_for_information\">\n  <strong>REQUEST_FOR_INFORMATION<\/strong>\n<\/a>\u00a0\u2013 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.<\/p>\n<\/li>\n<li>\n<p><a href=\"\/risk-management\/disputes-api\/dispute-notifications#notification_of_chargeback\">\n  <strong>NOTIFICATION_OF_CHARGEBACK<\/strong>\n<\/a>\u00a0\u2013 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 <a href=\"#supply-dispute-defense-documents\">upload the defense documentation<\/a>. The chargeback debit usually occurs a few days after you receive this webhook message.<\/p>\n<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p>After you receive a webhook message with any of these event codes, start the disputes process using the Disputes API.<\/p>\n<h2 id=\"retrieve-dispute-information\">Retrieve dispute information<\/h2>\n<p>To retrieve information about the dispute, you retrieve the applicable defense reasons and the required defense document types.<\/p>\n<ol>\n<li>\n<p>To get a list of applicable defense reasons and required document types, provide the following:<\/p>\n<ul>\n<li><code>disputePspReference<\/code>: The <code>pspReference<\/code> you received in the webhook message.<\/li>\n<li><code>merchantAccountCode<\/code>: The merchant account the dispute was placed through.<\/li>\n<\/ul>\n<p>Make a POST request to the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Disputes\/latest\/post\/retrieveApplicableDefenseReasons\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/retrieveApplicableDefenseReasons<\/a> endpoint.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/retrieveApplicableDefenseReasons request'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n\\t  \\\"disputePspReference\\\": \\\"FKSPNCQ8HXSKGK82\\\",\\n\\t  \\\"merchantAccountCode\\\": \\\"YOUR_MERCHANT_ACCOUNT\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>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.<\/p>\n<p>The following shows an example response when you have enabled <code>AlternativeDefenseMaterial<\/code> on your account. This lets you submit a generic dispute document in response to all chargebacks. To enable this option, contact our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a>.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/retrieveApplicableDefenseReasons response'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"defenseReasons\\\": [\\n        {\\n          \\\"defenseDocumentTypes\\\": [\\n              {\\n                \\\"available\\\": false,\\n                \\\"defenseDocumentTypeCode\\\": \\\"TIDorInvoice\\\",\\n                \\\"requirementLevel\\\": \\\"Optional\\\"\\n              },\\n              {\\n                \\\"available\\\": false,\\n                \\\"defenseDocumentTypeCode\\\": \\\"DefenseMaterial\\\",\\n                \\\"requirementLevel\\\": \\\"Required\\\"\\n              },\\n              {\\n                \\\"available\\\": false,\\n                \\\"defenseDocumentTypeCode\\\": \\\"AlternativeDefenseMaterial\\\",\\n                \\\"requirementLevel\\\": \\\"AlternativeRequired\\\"\\n              }\\n          ],\\n          \\\"defenseReasonCode\\\": \\\"SupplyDefenseMaterial\\\",\\n          \\\"satisfied\\\": false\\n        }\\n    ],\\n    \\\"disputeServiceResult\\\": {\\n      \\\"success\\\": true\\n    }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<\/ol>\n<p><br><\/p>\n<ol start=\"2\">\n<li>Get the <code>defenseReasonCode<\/code> and <code>defenseDocumentTypeCode<\/code> 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 <a href=\"\/risk-management\/understanding-disputes\/dispute-reason-codes\/#defense_requirements\">defense requirements<\/a> for more information on how to build a compelling disputes package. See the <a href=\"\/risk-management\/disputes-api\/disputes-api-reference\/\">Disputes API reference<\/a> for an overview of common <a href=\"\/risk-management\/disputes-api\/disputes-api-reference\/#dispute-defense-reason-code\">defense reason codes<\/a> and <a href=\"\/risk-management\/disputes-api\/disputes-api-reference\/#dispute-defense-document-type-code\">defense document type codes<\/a>.<\/li>\n<\/ol>\n<p>To defend the dispute, <a href=\"#supply-dispute-defense-documents\">gather and upload defense materials.<\/a>.<\/p>\n<h2 id=\"accept-dispute\">Optional: Accept the dispute<\/h2>\n<p>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  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Disputes\/latest\/post\/acceptDispute\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/acceptDispute<\/a> endpoint, providing the <code>disputePspReference<\/code> and the <code>merchantAccountCode<\/code>.<\/p>\n<h2 id=\"supply-dispute-defense-documents\">Upload dispute defense documents<\/h2>\n<p>After you identify which document types to include in your evidence package, you need to:<br \/>\n<a id=\"limitations\"><\/a><\/p>\n<ol>\n<li>\n<p>Check if your documents comply with the following <a href=\"\/risk-management\/understanding-disputes\/dispute-reason-codes\/#defense_requirements\">general guidelines and restrictions<\/a> 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 (<a href=\"\/get-started-with-adyen\/adyen-glossary\/#card-number-pan\">PAN<\/a>), and <a href=\"\/get-started-with-adyen\/adyen-glossary\/#sensitive-authentication-data\">sensitive authentication data<\/a>.<\/p>\n<p>You can supply defense documents in the following file formats:<\/p>\n<ul>\n<li>JPG (maximum file size 10 MB)<\/li>\n<li>TIFF (maximum file size 10 MB)<\/li>\n<li>PDF (maximum file size 2 MB)<\/li>\n<\/ul>\n<p>Specific requirements:<\/p>\n<ul>\n<li>For Diners and Discover, the maximum file size is 3 MB.<\/li>\n<li>For Mastercard, the maximum number of pages for a chargeback defense document is 19.<\/li>\n<li>Klarna only accepts defense documents in PDF format.<\/li>\n<li>For Mexico domestic chargeback defense documents, the maximum file size is 800 KB.<\/li>\n<li>For STAR, the maximum file size for JPG and TIFF formats is 5 MB.<\/li>\n<li>The maximum number of pages for an RFI defense document is 4.<\/li>\n<\/ul>\n<\/li>\n<\/ol>\n<p><br><\/p>\n<ol start=\"2\">\n<li>\n<p>To upload defense documents, provide the following:<\/p>\n<ul>\n<li><code>defenseDocuments<\/code>: An array of the defense documents.<\/li>\n<li><code>content<\/code>: The binary content of the document in a Base64 string.<\/li>\n<li><code>contentType<\/code>: The content type of the document. This can be one of:\n<ul>\n<li><strong>image\/jpg<\/strong><\/li>\n<li><strong>image\/jpeg<\/strong><\/li>\n<li><strong>image\/tiff<\/strong><\/li>\n<li><strong>application\/pdf<\/strong><\/li>\n<\/ul><\/li>\n<li><code>defenseDocumentTypeCode<\/code>: The corresponding document type code of the document.<\/li>\n<li><code>disputePspReference<\/code>: The <code>pspReference<\/code> you received in the webhook.<\/li>\n<li><code>merchantAccountCode<\/code>: The merchant account the dispute was placed through.<\/li>\n<\/ul>\n<p>Make a POST request to the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Disputes\/latest\/post\/supplyDefenseDocument\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/supplyDefenseDocument<\/a> endpoint.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/supplyDefenseDocument request'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"defenseDocuments\\\": [\\n        {\\n            \\\"content\\\": \\\"JVBERi0xLjMKJcTl8uXrp...\\\",\\n            \\\"contentType\\\": \\\"application\\\/pdf\\\",\\n            \\\"defenseDocumentTypeCode\\\": \\\"MerchandiseDescription\\\"\\n        }\\n    ],\\n    \\\"disputePspReference\\\": \\\"MLSPNCQ8HXSKGK82\\\",\\n    \\\"merchantAccountCode\\\": \\\"YOUR_MERCHANT_ACCOUNT\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>The response contains the <code>success<\/code> field, a boolean that indicates if the request was successful. If the request fails, the response also contains an <code>errorMessage<\/code> field. See <a href=\"\/risk-management\/disputes-api\/disputes-api-reference\/\">Disputes API reference<\/a> for a list of possible errors.<\/p>\n<\/li>\n<\/ol>\n<div class=\"sc-notice note\"><div>\n<p>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 <a href=\"#defend-dispute\">defend dispute<\/a> API request.<\/p>\n<\/div><\/div>\n<h3 id=\"delete-dispute-defense-documents\">Optional: Delete dispute defense documents<\/h3>\n<p>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.<\/p>\n<ol>\n<li>\n<p>To delete defense material, provide the following:<\/p>\n<ul>\n<li><code>defenseDocumentType<\/code>: The defense document type to delete.<\/li>\n<li><code>disputePspReference<\/code>: The <code>pspReference<\/code> you received in the webhook.<\/li>\n<li><code>merchantAccountCode<\/code>: The merchant account the dispute was placed through.<\/li>\n<\/ul>\n<p>Make a POST request to the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Disputes\/latest\/post\/deleteDisputeDefenseDocument\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/deleteDisputeDefenseDocument<\/a> endpoint.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/deleteDisputeDefenseDocument request'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"defenseDocumentType\\\": \\\"MerchandiseDescription\\\",\\n  \\\"disputePspReference\\\": \\\"MLSPNCQ8HXSKGK82\\\",\\n  \\\"merchantAccountCode\\\": \\\"YOUR_MERCHANT_ACCOUNT\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>The response contains the <code>success<\/code> field, a boolean that indicates if the request was successful. If the request fails, the response also contains an <code>errorMessage<\/code> field. See <a href=\"\/risk-management\/disputes-api\/disputes-api-reference\/\">Disputes API reference<\/a> for a list of possible errors.<\/p>\n<\/li>\n<li>\n<p><a href=\"#supply-dispute-defense-documents\">Upload<\/a> new defense documents.<\/p>\n<\/li>\n<\/ol>\n<h2 id=\"defend-dispute\">Defend the dispute<\/h2>\n<div class=\"sc-notice note\"><div>\n<p>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.<\/p>\n<\/div><\/div>\n<ol>\n<li>\n<p>When you are ready to submit your complete defense to the scheme, provide the following:<\/p>\n<ul>\n<li><code>defenseReasonCode<\/code>: Code identifying the defense reason.<\/li>\n<li><code>disputePspReference<\/code>: The <code>pspReference<\/code> you received in the webhook message.<\/li>\n<li><code>merchantAccountCode<\/code>: The merchant account the dispute was placed through.<\/li>\n<\/ul>\n<p>Make a POST request to the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/Disputes\/latest\/post\/defendDispute\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">\/defendDispute<\/a> endpoint.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/defendDispute request'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"defenseReasonCode\\\": \\\"SupplyDefenseMaterial\\\",\\n    \\\"disputePspReference\\\": \\\"MLSPNCQ8HXSKGK82\\\",\\n    \\\"merchantAccountCode\\\": \\\"YOUR_MERCHANT_ACCOUNT\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>The response contains the <code>success<\/code> field, a boolean that indicates if the request was successful. If the request fails, the response also contains an <code>errorMessage<\/code> field. See <a href=\"\/risk-management\/disputes-api\/disputes-api-reference\/\">Disputes API reference<\/a> for a list of possible errors.<\/p>\n<\/li>\n<li>\n<p>Keep track of the status of the dispute by listening to the <a href=\"\/risk-management\/disputes-api\/dispute-notifications\">dispute webhook messages<\/a> that you receive.<\/p>\n<\/li>\n<\/ol>\n<h2 id=\"pre-arbitration-disputes-api\">Optional: Handle pre-arbitration cases<\/h2>\n<p>When you are eligible, you can decide to accept or decline a pre-arbitration case.<\/p>\n<ol>\n<li>When the issuer opens a pre-arbitration case, you will receive a <strong>PRE_ARBITRATION_OPEN<\/strong> <a href=\"#handle-dispute-notifications\">webhook message<\/a>.<\/li>\n<li>Decide what you want to do:\n<ol>\n<li><a href=\"#pre-arbitration-accept\">Accept<\/a> the pre-arbitration case.<\/li>\n<li><a href=\"#pre-arbitration-accept-partially\">Partially accept<\/a> the pre-arbitration case.<\/li>\n<li><a href=\"#pre-arbitration-decline\">Decline<\/a> the pre-arbitration case.<\/li>\n<\/ol><\/li>\n<\/ol>\n<h3 id=\"pre-arbitration-accept\">Accept a pre-arbitration case<\/h3>\n<p>When you accept the pre-arbitration case, the dispute is lost, and you receive a second chargeback.<\/p>\n<ol>\n<li>\n<p>When you are ready to accept the pre-arbitration case, provide the following:<\/p>\n<ul>\n<li><code>disputePspReference<\/code>: The <code>pspReference<\/code> of the dispute that you want to accept.<\/li>\n<li><code>merchantAccountCode<\/code>: The merchant account the dispute was placed through.<\/li>\n<\/ul>\n<p>Make a POST request to the <code>\/acceptPreArbitration<\/code> endpoint.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/acceptPreArbitration request'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"disputePspReference\\\": \\\"ZC4R4RBFJGXXGN82\\\",\\n    \\\"merchantAccountCode\\\": \\\"YOUR_MERCHANT_ACCOUNT\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Listen to the webhook message <strong>PRE_ARBITRATION_ACCEPTED<\/strong>.<\/p>\n<\/li>\n<li>\n<p>The dispute is lost. Listen to the webhook message <strong>SECOND_CHARGEBACK<\/strong>.<\/p>\n<\/li>\n<\/ol>\n<h3 id=\"pre-arbitration-accept-partially\">Partially accept a pre-arbitration case<\/h3>\n<p>When you partially accept a pre-arbitration case, you agree to accept a portion of the disputed amount.<\/p>\n<ol>\n<li>\n<p>When you are ready to partially accept the pre-arbitration case, provide the following:<\/p>\n<ul>\n<li><code>disputePspReference<\/code>: The <code>pspReference<\/code> of the dispute.<\/li>\n<li><code>merchantAccountCode<\/code>: The merchant account the dispute was placed through.<\/li>\n<li><code>amount<\/code>: The value and currency that you want to accept. This must be less than the total amount of the disputed transaction.<\/li>\n<li><code>reason<\/code>: A reason or explanation of why you partially accept the case.<\/li>\n<\/ul>\n<p>Make a POST request to the <code>\/partialAcceptPreArbitration<\/code> endpoint.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/partialAcceptPreArbitration request'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"disputePspReference\\\": \\\"XB7XNCQ8HXSKGK82\\\",\\n    \\\"merchantAccountCode\\\": \\\"YOUR_MERCHANT_ACCOUNT\\\",\\n    \\\"amount\\\": {\\n        \\\"value\\\": 1000,\\n        \\\"currency\\\": \\\"EUR\\\"\\n    },\\n    \\\"reason\\\": \\\"The reason why you partially accept the pre-arbitration case.\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Listen to the webhook message <strong>PRE_ARBITRATION_ACCEPTED<\/strong>. <\/p>\n<\/li>\n<li>\n<p>The dispute is partially lost. Listen to the webhook message <strong>SECOND_CHARGEBACK<\/strong>. <\/p>\n<\/li>\n<\/ol>\n<h3 id=\"pre-arbitration-decline\">Decline a pre-arbitration case<\/h3>\n<p>If you decline the pre-arbitration, the case can be sent to scheme arbitration. We recommend that you only decline if you are confident that the chargeback is not valid, and that the defense materials provided during the first chargeback defense were sufficient.<\/p>\n<p>During scheme arbitration, the scheme rules on the chargeback liability based on the information provided throughout chargeback defense timelines. If the scheme rules in favor of the issuer, you can incur a fee of up to USD 600. This fee is added to the second chargeback.<\/p>\n<ol>\n<li>\n<p>When you are ready to decline the pre-arbitration case, provide the following:<\/p>\n<ul>\n<li><code>disputePspReference<\/code>: The <code>pspReference<\/code> of the dispute.<\/li>\n<li><code>merchantAccountCode<\/code>: The merchant account the dispute was placed through.<\/li>\n<li><code>declineReason<\/code>: A reason or explanation of why you decline the case.<\/li>\n<\/ul>\n<p>Make a POST request to the <code>\/declinePreArbitration<\/code> endpoint.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Example \/declinePreArbitration request'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n    \\\"disputePspReference\\\": \\\"WNKH9MC2XJMLNK82\\\",\\n    \\\"merchantAccountCode\\\": \\\"YOUR_MERCHANT_ACCOUNT\\\",\\n    \\\"declineReason\\\": \\\"The reason why you decline the pre-arbitration case.\\\"\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<li>\n<p>Listen to the webhook message <strong>PRE_ARBITRATION_DECLINED<\/strong>.<\/p>\n<\/li>\n<li>\n<p>The case may be sent to scheme arbitration. To know if that happens, listen to the webhook message <strong>SCHEME_ARBITRATION<\/strong>. The scheme arbitration process can take several months to complete.<\/p>\n<ol>\n<li>When you get the webhook message <strong>SCHEME_ARBITRATION_WON<\/strong>, you win the dispute, and the money is returned to your account.<\/li>\n<li>When you get the webhook message <strong>SCHEME_ARBITRATION_LOST<\/strong>, you loose the dispute, and a fee is added to the <strong>SECOND_CHARGEBACK<\/strong>.<\/li>\n<\/ol>\n<\/li>\n<\/ol>\n<h2 id=\"see-also\">See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/risk-management\/understanding-disputes\"\n                        target=\"_self\"\n                        >\n                    Understanding disputes\n                <\/a><\/li><li><a href=\"\/risk-management\/disputes-api\/dispute-notifications\"\n                        target=\"_self\"\n                        >\n                    Dispute webhooks\n                <\/a><\/li><li><a href=\"\/risk-management\/disputes-api\/disputes-api-reference\"\n                        target=\"_self\"\n                        >\n                    Disputes API reference\n                <\/a><\/li><li><a href=\"\/risk-management\/disputes-api\/test-applicable-dispute-reasons\"\n                        target=\"_self\"\n                        >\n                     Test a chargeback scenario\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/risk-management\/disputes-api","articleFields":{"description":"Automate your process of handling disputes using our Defend Disputes API.","last_edit_on":"27-05-2020 10:40","page_id":"e6bd4545-4054-4d92-8c7b-b52688f01586","feedback_component":true,"filters_component":false,"decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/risk-management\/disputes-api","title":"Manage disputes with the Disputes API","content":"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.\nIf you want to handle disputes manually instead, you can manage disputes through the Customer Area.\nRequirements\nBefore you begin, take into account the following requirements and limitations.\n\n\n\nRequirement\nDescription\n\n\n\n\nIntegration type\nMake sure that you have built an online payments integration.\n\n\nAPI credentials\nMake sure that you have an API credential with an API key and the API dispute management role. If the role is not available for your admin user, contact our Support Team.\n\n\n\n\nWebhooks\nTo follow disputes using webhooks, subscribe to the Standard webhook and enable dispute events.\n\n\nLimitations\nNot all dispute types can be defended.\n\n\nSetup steps\nBefore you begin, make sure that you: Understand the general dispute flow.Review the chargeback guidelines for specific card schemes and other payment methods that you use.Know the scenarios when Adyen automatically handles disputes on your behalf.\n\n\n\nHow it works\nThe overall process is as follows:\n\nHandle dispute webhooks. Use the webhook messages and event codes to determine the dispute status.\nRetrieve dispute information to understand how you can defend the dispute.\n\nIf you want to defend the dispute, gather and upload defense materials.\nOptional: If you do not want to defend the dispute, accept the dispute.\n\nUpload all relevant defense material for the dispute.\n\nOptional: Before defending the dispute, it is possible to delete defense documents that you uploaded previously.\n\nSubmit your complete defense to the scheme and defend the dispute.\n\nFor a list of endpoints and parameters, see  Disputes API. To test your integration, you can simulate different chargeback scenarios.\n\nOptional: Handle pre-arbitration cases.\nFor some dispute flows, the issuer can open a pre-arbitration case if they decline your defense. When you are eligible, and the dispute flow supports it, you can accept or decline the pre-arbitration case yourself. This requires additional configuration and approval from Adyen. Reach out to our Support Team or your Adyen contact for more details.\n\nHandle dispute webhooks\nAdyen sends you a webhook message when a payment is disputed. For a list of all event types related to disputes, see Dispute webhooks.\n\n\nWhen a shopper starts a dispute process with their issuer, you receive a webhook message when any of the following events happen:\n\n\n\n  REQUEST_FOR_INFORMATION\n\u00a0\u2013 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.\n\n\n\n  NOTIFICATION_OF_CHARGEBACK\n\u00a0\u2013 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.\n\n\n\n\nAfter you receive a webhook message with any of these event codes, start the disputes process using the Disputes API.\nRetrieve dispute information\nTo retrieve information about the dispute, you retrieve the applicable defense reasons and the required defense document types.\n\n\nTo get a list of applicable defense reasons and required document types, provide the following:\n\ndisputePspReference: The pspReference you received in the webhook message.\nmerchantAccountCode: The merchant account the dispute was placed through.\n\nMake a POST request to the  \/retrieveApplicableDefenseReasons endpoint.\n\n\n\nThe 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.\nThe 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.\n\n\n\n\n\n\n\nGet 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.\n\nTo defend the dispute, gather and upload defense materials..\nOptional: Accept the dispute\nIf 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.\nUpload dispute defense documents\nAfter you identify which document types to include in your evidence package, you need to:\n\n\n\nCheck 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.\nYou can supply defense documents in the following file formats:\n\nJPG (maximum file size 10 MB)\nTIFF (maximum file size 10 MB)\nPDF (maximum file size 2 MB)\n\nSpecific requirements:\n\nFor Diners and Discover, the maximum file size is 3 MB.\nFor Mastercard, the maximum number of pages for a chargeback defense document is 19.\nKlarna only accepts defense documents in PDF format.\nFor Mexico domestic chargeback defense documents, the maximum file size is 800 KB.\nFor STAR, the maximum file size for JPG and TIFF formats is 5 MB.\nThe maximum number of pages for an RFI defense document is 4.\n\n\n\n\n\n\nTo upload defense documents, provide the following:\n\ndefenseDocuments: An array of the defense documents.\ncontent: The binary content of the document in a Base64 string.\ncontentType: The content type of the document. This can be one of:\n\nimage\/jpg\nimage\/jpeg\nimage\/tiff\napplication\/pdf\n\ndefenseDocumentTypeCode: The corresponding document type code of the document.\ndisputePspReference: The pspReference you received in the webhook.\nmerchantAccountCode: The merchant account the dispute was placed through.\n\nMake a POST request to the  \/supplyDefenseDocument endpoint.\n\n\n\nThe 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.\n\n\n\nAfter 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.\n\nOptional: Delete dispute defense documents\nIf the defense documents you uploaded are incomplete or are not compelling enough, you can still delete the documents and re-upload new defense material.\n\n\nTo delete defense material, provide the following:\n\ndefenseDocumentType: The defense document type to delete.\ndisputePspReference: The pspReference you received in the webhook.\nmerchantAccountCode: The merchant account the dispute was placed through.\n\nMake a POST request to the  \/deleteDisputeDefenseDocument endpoint.\n\n\n\nThe 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.\n\n\nUpload new defense documents.\n\n\nDefend the dispute\n\nThis 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.\n\n\n\nWhen you are ready to submit your complete defense to the scheme, provide the following:\n\ndefenseReasonCode: Code identifying the defense reason.\ndisputePspReference: The pspReference you received in the webhook message.\nmerchantAccountCode: The merchant account the dispute was placed through.\n\nMake a POST request to the  \/defendDispute endpoint.\n\n\n\nThe 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.\n\n\nKeep track of the status of the dispute by listening to the dispute webhook messages that you receive.\n\n\nOptional: Handle pre-arbitration cases\nWhen you are eligible, you can decide to accept or decline a pre-arbitration case.\n\nWhen the issuer opens a pre-arbitration case, you will receive a PRE_ARBITRATION_OPEN webhook message.\nDecide what you want to do:\n\nAccept the pre-arbitration case.\nPartially accept the pre-arbitration case.\nDecline the pre-arbitration case.\n\n\nAccept a pre-arbitration case\nWhen you accept the pre-arbitration case, the dispute is lost, and you receive a second chargeback.\n\n\nWhen you are ready to accept the pre-arbitration case, provide the following:\n\ndisputePspReference: The pspReference of the dispute that you want to accept.\nmerchantAccountCode: The merchant account the dispute was placed through.\n\nMake a POST request to the \/acceptPreArbitration endpoint.\n\n\n\n\n\nListen to the webhook message PRE_ARBITRATION_ACCEPTED.\n\n\nThe dispute is lost. Listen to the webhook message SECOND_CHARGEBACK.\n\n\nPartially accept a pre-arbitration case\nWhen you partially accept a pre-arbitration case, you agree to accept a portion of the disputed amount.\n\n\nWhen you are ready to partially accept the pre-arbitration case, provide the following:\n\ndisputePspReference: The pspReference of the dispute.\nmerchantAccountCode: The merchant account the dispute was placed through.\namount: The value and currency that you want to accept. This must be less than the total amount of the disputed transaction.\nreason: A reason or explanation of why you partially accept the case.\n\nMake a POST request to the \/partialAcceptPreArbitration endpoint.\n\n\n\n\n\nListen to the webhook message PRE_ARBITRATION_ACCEPTED. \n\n\nThe dispute is partially lost. Listen to the webhook message SECOND_CHARGEBACK. \n\n\nDecline a pre-arbitration case\nIf you decline the pre-arbitration, the case can be sent to scheme arbitration. We recommend that you only decline if you are confident that the chargeback is not valid, and that the defense materials provided during the first chargeback defense were sufficient.\nDuring scheme arbitration, the scheme rules on the chargeback liability based on the information provided throughout chargeback defense timelines. If the scheme rules in favor of the issuer, you can incur a fee of up to USD 600. This fee is added to the second chargeback.\n\n\nWhen you are ready to decline the pre-arbitration case, provide the following:\n\ndisputePspReference: The pspReference of the dispute.\nmerchantAccountCode: The merchant account the dispute was placed through.\ndeclineReason: A reason or explanation of why you decline the case.\n\nMake a POST request to the \/declinePreArbitration endpoint.\n\n\n\n\n\nListen to the webhook message PRE_ARBITRATION_DECLINED.\n\n\nThe case may be sent to scheme arbitration. To know if that happens, listen to the webhook message SCHEME_ARBITRATION. The scheme arbitration process can take several months to complete.\n\nWhen you get the webhook message SCHEME_ARBITRATION_WON, you win the dispute, and the money is returned to your account.\nWhen you get the webhook message SCHEME_ARBITRATION_LOST, you loose the dispute, and a fee is added to the SECOND_CHARGEBACK.\n\n\n\nSee also\n\n\n                    Understanding disputes\n                \n                    Dispute webhooks\n                \n                    Disputes API reference\n                \n                     Test a chargeback scenario\n                \n","type":"page","locale":"en","boost":18,"hierarchy":{"lvl0":"Home","lvl1":"Risk management","lvl2":"Manage disputes with the Disputes API"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/risk-management","lvl2":"\/risk-management\/disputes-api"},"levels":3,"category":"Risk Management","category_color":"green","tags":["Manage","disputes","Disputes"]},"articleFiles":{"defend_dispute_req.json":"<p alt=\"\">defend_dispute_req.json<\/p>","defend_dispute_res.json":"<p alt=\"\">defend_dispute_res.json<\/p>","delete_defense_document_req.json":"<p alt=\"\">delete_defense_document_req.json<\/p>","delete_defense_document_res.json":"<p alt=\"\">delete_defense_document_res.json<\/p>","retrieve_applicable_defense_reasons_req.json":"<p alt=\"\">retrieve_applicable_defense_reasons_req.json<\/p>","retrieve_applicable_defense_reasons_res.json":"<p alt=\"\">retrieve_applicable_defense_reasons_res.json<\/p>","supply_defense_document_req.json":"<p alt=\"\">supply_defense_document_req.json<\/p>","supply_defense_document_res.json":"<p alt=\"\">supply_defense_document_res.json<\/p>"}}