Adyen Disputes API

Name: Adyen Disputes API API
Brand: Adyen Disputes API
Availability: InStock

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

Quickstart

Get started with Adyen Disputes API in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"defend an Adyen chargeback dispute"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

Capabilities

What an agent can do with Adyen Disputes API 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

GET STARTED

Start building with Adyen Disputes API API

Explore with Jentic

View OpenAPI Spec

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.

Use Cases

Patterns agents use Adyen Disputes API 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 though 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.

Complementary

Adyen Checkout API

Authorises the payments that later get disputed

Use Checkout to process payments and Disputes to respond when those payments are charged back

Complementary

Adyen Management Webhooks

Webhook events that signal when a new dispute or chargeback arrives

Use Management Webhooks to subscribe to dispute notifications and the Disputes API to act on them

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