Adyen Disputes API

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

✓ Official Vendor SpecPaymentsPayment ProcessingapiKey, basic5 EndpointsREST

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.

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

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 instance

Jentic 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

GET STARTED

Start building with Adyen Disputes API

Explore with Jentic

View OpenAPI Document

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.

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 your Jentic One instance 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

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.

Intent-based discovery

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.

Time to first call

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

Adyen Disputes API

Connect the Adyen Disputes API to your agent

Capabilities

Start building with Adyen Disputes API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs