Adyen Disputes API
Browse all Adyen APIs✓ Official Vendor SpecPaymentsPayment ProcessingapiKey, basic5 EndpointsREST
For Agents
Accept, defend, and supply or remove evidence on Adyen disputes and chargebacks, plus look up which defense reasons apply to a given dispute.
Use for: I need to defend a chargeback raised against a recent payment, Accept a dispute that we cannot contest and stop further fees, Upload shipping proof as evidence for a friendly fraud chargeback, Get the list of defense reasons that apply to a specific dispute
Not supported: Does not handle payment authorisation, refunds, or fraud risk scoring — use for chargeback and dispute response workflows only.
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.
Install Jentic One Beta
Connect the Adyen Disputes API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Adyen Disputes API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Adyen Disputes API.
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
Patterns agents use Adyen Disputes API for, with concrete tasks.
★ 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.
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.
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.
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 the Jentic vault throughout.
Search Jentic for 'retrieve Adyen defense reasons', load the schema, and call /retrieveApplicableDefenseReasons for the dispute referenced in the support ticket
Key Endpoints
5 endpoints — 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.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Adyen X-API-Key credentials are stored encrypted in the Jentic MAXsystem vault. Agents call /defendDispute, /acceptDispute, and the document operations through scoped tokens, so the raw API key never lands in agent prompts or logs.
Intent-based discovery
Agents search by intent ('defend an Adyen chargeback', 'accept a dispute', 'upload defense document') and Jentic returns the matching Disputes operation with the request schema and supported defense reason codes.
Time to first call
Direct integration: 2-4 days for auth, webhook ingestion, evidence pipeline, and defense logic. Through Jentic: under 1 hour to wire each operation — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
Alternative
Stripe API
Stripe Disputes resource provides similar accept and defend operations on Stripe payments
Choose Stripe Disputes when your acquirer is Stripe; choose Adyen Disputes for chargebacks on Adyen-acquired transactions
FAQs
Specific to using Adyen Disputes API through Jentic.
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 the MAXsystem vault 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. Sign up at https://app.jentic.com/sign-up to get started.
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.
GET STARTED