canonical: https://jentic.com/apis/adyen.com/adyen-dispute-service-v30 # Adyen Disputes API Automate the dispute and chargeback response cycle on Adyen by accepting or defending disputes, supplying defense documents, and retrieving the defense reasons applicable to a given dispute. The API exposes five operations covering the response side of the dispute workflow, with all calls going to /ca/services/DisputeService/v30. Suitable for merchants that want to react to chargebacks programmatically rather than through the Customer Area UI. ## For AI agents Accept, defend, and supply or remove evidence on Adyen disputes and chargebacks, plus look up which defense reasons apply to a given dispute. ## Scope Does not handle payment authorisation, refunds, or fraud risk scoring - use for chargeback and dispute response workflows only. ## Capabilities - Defend a dispute by selecting a defense reason and submitting required evidence - Accept a chargeback to settle the dispute without contesting it - Supply defense documents (receipts, shipping proof, signed authorisation) to back a defense - Delete previously uploaded defense documents before the dispute is finalised - Retrieve the defense reasons that apply to a specific dispute and the documents each reason requires ## Use cases ### Automated Chargeback Defense Wire dispute notifications from Adyen webhooks into a defense pipeline that automatically gathers evidence (delivery confirmation, customer correspondence, signed receipts), uploads it through /supplyDefenseDocument, and submits the response through /defendDispute. Works best for chargebacks with documented delivery and AVS-matched cards, where defense success rates are highest. Reduces the manual reviewer load while keeping the operations team in control of edge cases. Example prompt: POST /retrieveApplicableDefenseReasons with the disputePspReference, upload the matching shipping proof via /supplyDefenseDocument, then call /defendDispute with the chosen defenseReasonCode ### Bulk Dispute Triage Route inbound dispute webhooks through a triage rule that decides whether to defend or accept each dispute based on amount, dispute reason, and historical win rate. Low-value disputes below a configurable threshold call /acceptDispute to stop further fees, while higher-value disputes go through the defense pipeline. The API's narrow surface - five operations - makes the rule engine straightforward to maintain. Example prompt: For each dispute under 10 EUR, POST /acceptDispute with the disputePspReference and merchantAccountCode and log the action in the disputes_audit table ### Evidence Document Lifecycle Manage the lifecycle of evidence documents attached to a dispute, from upload through replacement and removal before the response deadline. Use /supplyDefenseDocument to attach files (limited by Adyen's per-document size constraints) and /deleteDisputeDefenseDocument to remove ones that were uploaded incorrectly. Documents are scoped to a single disputePspReference and replaced rather than versioned. Example prompt: Upload a signed delivery receipt via POST /supplyDefenseDocument with defenseDocumentTypeCode DeliveryConfirmation, verify the upload, then proceed to defend the dispute ### AI Agent Dispute Handling AI agents in operations or customer support tooling can respond to disputes through Jentic without holding raw Adyen credentials. The agent searches for 'defend an Adyen dispute' via Jentic, retrieves the /defendDispute schema with required defense reason and dispute reference, and executes the call after gathering supporting evidence from internal systems. Credentials remain isolated in your Jentic One instance throughout. Example prompt: Search Jentic for 'retrieve Adyen defense reasons', load the schema, and call /retrieveApplicableDefenseReasons for the dispute referenced in the support ticket ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | /retrieveApplicableDefenseReasons | Get applicable defense reasons for a dispute | | POST | /supplyDefenseDocument | Upload a defense document for a dispute | | POST | /deleteDisputeDefenseDocument | Delete a previously uploaded defense document | | POST | /defendDispute | Defend a dispute with a chosen defense reason | | POST | /acceptDispute | Accept a dispute without contesting | ## Key resources - **Disputes** — Chargeback and dispute records to accept or defend - **Defense Reasons** — Reason codes that justify defending a dispute, with associated required documents - **Defense Documents** — Evidence files uploaded to support a defense, such as shipping proof or signed receipts ## Why Jentic - **Setup:** Wiring the Adyen Disputes API by hand means handling its X-API-Key or basic auth, targeting the classic CA host, and matching each response to the supported defense reason codes. Through Jentic you install once, import the Disputes API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Disputes takes the dispute reference in the request body rather than a resource id in the URL path, so you limit the agent to the operations it needs, such as retrieving applicable defense reasons or supplying a defense document. Because you pick the operations, accepting a dispute or deleting a document stays out unless you include it. - **Credential handling:** Your Adyen X-API-Key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'defend an adyen chargeback' or 'upload a defense document', and Jentic returns the matching Disputes operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adyen Checkout API** — Authorises the payments that later get disputed - **Adyen Management Webhooks** — Webhook events that signal when a new dispute or chargeback arrives - **Stripe API** — Stripe Disputes resource provides similar accept and defend operations on Stripe payments ## FAQ ### What authentication does the Adyen Disputes API use? The Disputes API accepts an API key in the X-API-Key header or HTTP Basic authentication with web service user credentials. Generate the key from your Adyen Customer Area. Through Jentic, the X-API-Key is held encrypted in your Jentic One instance and agents authenticate with scoped tokens, keeping the raw key out of agent context. ### Can I defend a dispute without first calling retrieveApplicableDefenseReasons? Technically yes, but you risk submitting a defense reason that does not apply to the dispute, which causes the defense to be rejected. The recommended flow is to call POST /retrieveApplicableDefenseReasons first, pick a returned defenseReasonCode, upload required documents via /supplyDefenseDocument, then call /defendDispute. ### What are the rate limits for the Adyen Disputes API? Adyen applies per-merchant rate limits in the tens of requests per second for dispute operations on production, lower in test. Excess requests return HTTP 429. Bulk dispute triage flows should batch work and back off on rate-limit responses; contact your Adyen account team if you need a higher ceiling. ### How do I upload defense evidence through Jentic? Search Jentic for 'supply Adyen dispute defense document' to find the POST /supplyDefenseDocument operation. Required fields are disputePspReference, defenseDocumentTypeCode, and the base64-encoded content. Jentic loads the full schema including supported document type codes. Run it through Jentic One, the self-hosted execution layer. ### Can I retract a dispute defense after submitting it? No. Once /defendDispute is called the response is locked in and cannot be retracted through the API. You can still delete or replace defense documents before calling /defendDispute using /deleteDisputeDefenseDocument and /supplyDefenseDocument, but after the defense is submitted the only path is to wait for the issuer's decision. ### Can I limit what my agent is allowed to do with the Adyen Disputes API? Yes. Because you run Jentic One yourself, your own rules decide which of the five dispute operations and which credentials the agent may use. The Disputes API takes the dispute reference in the request body rather than in the URL path, so you scope the agent to only the operations it needs, such as retrieving applicable defense reasons via /retrieveApplicableDefenseReasons or supplying evidence via /supplyDefenseDocument. Higher-impact calls like accepting a dispute with /acceptDispute or removing a document with /deleteDisputeDefenseDocument stay out of reach unless you explicitly grant them, and the raw API key stays in your own instance rather than the agent's context.