Chargeback API and Dispute API Compared: Stripe, Adyen, PayPal and Chargeflow

A chargeback API, also called a dispute API, is a programmatic interface that lets software read dispute cases, submit or generate evidence and respond before a deadline. Stripe, Adyen and PayPal each expose a different slice of that lifecycle, so a platform that supports more than one processor needs a field mapping, not one assumption about what "the dispute API" returns.

This guide compares what the three processor APIs return and accept, as documented on 11 October 2026, then suggests a mapping from their fields to a common model and separates the two Chargeflow APIs: the merchant API and the platforms API. It stays at the API layer. For the operating model around it, see chargeback management for payment platforms.

What a chargeback API can cover

Three different things get called a chargeback API, and they answer different questions.

Which one you need depends on whether you are a merchant or a payment service provider or platform handling disputes for many merchants.

How the Stripe, Adyen and PayPal dispute APIs compare

Stripe and PayPal let you read a dispute at any time, Adyen's Disputes API page lists no read call, and each provider puts the response deadline in a different field. Every row below comes from official documentation, checked on 11 October 2026.

Sources: Stripe Dispute object, Stripe Update a dispute, Stripe event types, Adyen Disputes API, Adyen dispute notifications, PayPal Disputes v1, PayPal dispute reference, PayPal dispute definition.

The read path is the biggest structural difference. The endpoints listed on Adyen's Disputes API page cover defending and accepting, so a platform on Adyen has to persist the case from webhook payloads: pspReference identifies the dispute and originalReference identifies the disputed payment. Provider-level workflows are in the Stripe chargebacks guide, the Adyen chargebacks guide and the PayPal dispute versus chargeback guide.

The second difference is staging. Stripe can hold evidence on the dispute with submit=false and send it later, but Stripe's object reference says you may typically submit evidence only once. Adyen does not send uploaded documents to the issuer until you call /defendDispute, and you cannot add information afterwards. Model "ready to submit" and "submitted" as separate states in your own case record. Stripe also states that if evidence_details.past_due is true, delivery of the latest evidence is not guaranteed, so alert on the deadline field rather than on the status.

Evidence formats and limits differ by provider

Stripe takes text fields and file IDs, Adyen takes base64 documents, and PayPal takes typed evidence in a multipart request.

Sources: Stripe disputes API guide, Stripe responding to disputes, Adyen Disputes API (linked above), PayPal disputes API guide.

Stripe also reports whether a dispute qualifies for Visado Compelling Evidence 3.0. Under evidence_details.enhanced_eligibility.visa_compelling_evidence_3, status is qualified, requires_action or not_qualified, and required_actions lists what is missing. The value missing_customer_identifiers means the disputed and prior undisputed transactions need at least two customer identifiers (account ID, email, shipping address, purchase IP, device ID or device fingerprint), one of them the purchase IP, device ID or fingerprint, and never device ID and fingerprint alone. Capture those fields at order time, not at dispute time.

Effective 24 October 2026, Visa's April 2026 rules let the two prior transactions come from more than one merchant, not only the disputing merchant (Visa Core Rules, 18 April 2026).

Response windows differ by network and acquirer

Per Adyen's documentation, defense windows run in calendar days from the notice of chargeback date and differ by network. These are Adyen's deadlines for its merchants, so confirm them against the current network rulebook and your acquirer.

Source: Adyen dispute timeframes, Adyen's response deadlines in calendar days from the notice of chargeback date.

Windows vary by network, region and acquirer, so store the deadline the provider returns as one absolute timestamp rather than computing it from a constant. Stripe returns Unix seconds, Adyen's sample shows ISO 8601 with an offset, and Chargeflow's platform API expects an ISO 8601 due_by. Convert once at ingestion. For network clocks, see Visa chargeback time limits and the Mastercard chargeback time limit guide.

Field mapping from processor APIs to a common model

Both mappings in this section are suggestions, not provider documentation. The left column is a suggested internal model, the provider columns quote documented fields, and the last column is what Chargeflow's Platforms API requires to create a dispute record. Platforms that route across several processors need exactly this layer; see multi-processor chargeback recovery.

Sources: provider references linked above and Chargeflow Submit Platform Disputes.

The platform record also requires account_id, amount and currency. Chargeflow documents amount as a number in the transaction currency, no greater than the transaction amount, and currency as an uppercase ISO 4217 code, while Stripe returns an integer amount and a lowercase code. The Chargeflow and Adyen pages reviewed do not say whether amounts are in minor units, so confirm the unit and convert once at ingestion. Each merchant is created first through the Platforms API accounts endpoint, which accepts an optional ext_account_id so your own merchant identifier travels with the Chargeflow account.

Chargeflow accepts seven reason values, so reasons need translating too. Adyen returns network reason codes such as 10.4 and PayPal has its own reason field, so each needs a lookup. Suggested mapping from Stripe's reasons:

Status needs its own normalization step because the three vocabularies do not line up. The table below is a suggested mapping to the four statuses Chargeflow accepts.

Keep the provider's raw status next to the normalized one. Pending appears at several Adyen events, so read eventCode alongside disputeStatus, and give PayPal outcome codes such as CANCELED_BY_BUYER their own rule. Support teams and reconciliation both need the original value, and the chargeback reason codes attached to a case rarely survive translation into a single internal enum.

A reference integration flow

The flow below is a general architecture. The tables above give the provider-specific calls, and your account entitlements decide which are available.

Each step has a failure case, such as a missing merchant mapping, an ambiguous transaction or incomplete evidence. Route those cases to an exception queue well before the response deadline.

Evidence generation is not submission

An evidence API returns a document or structured output for a case. That output does not establish that a response reached the processor, and sending it is the chargeback representment step. Chargeflow's Evidence-as-a-Service returns one versioned PDF per dispute, and the documented flow is to verify the webhook signature, download and store the PDF, then submit it to your PSP before the dispute's due_by, the deadline stored on the dispute record. Automated chargeback evidence generation explains how the package is assembled, and the chargeback evidence source map shows which system usually holds each proof.

In a hybrid model the platform uses generated evidence inside its own submission process. It must keep package review, decision authority and a record of the version actually sent. The table shows that split for Evidence-as-a-Service.

The automated chargeback management guide describes where each step normally sits.

Build reliability into the case model

Events are notifications, not a recovery mechanism. Reconcile through list endpoints after an outage, such as Stripe's GET /v1/disputes with a created filter, and never let a delayed event overwrite a newer state. Delivery rules differ: Stripe retries live events for up to three days and does not guarantee order (Stripe webhooks), Adyen queues failed webhooks and retries them for up to 30 days (Adyen webhook troubleshooting), and Chargeflow retries until your endpoint returns a 2XX response or its retry limit is reached. Neither Adyen nor Chargeflow states an ordering guarantee, and Chargeflow publishes no retry count or schedule, so treat those as unspecified. Dispute webhooks covers delivery design in detail.

Version evidence separately from the case. Store evidence.id rather than the download URL, which expires 7 days after issue, and expect file_version to increment on each regeneration. After evidence.error, which fires once automatic retries are exhausted, nothing retries until Generate Evidence is called again. The merchant API returns 429 with a Retry-After header, and numeric rate limits are still to be published.

Protect tenant boundaries and data access

Chargeflow merchant API and platforms API

Chargeflow documents two API surfaces under the same version path, 2025-04-01. They are not interchangeable. The merchant API overview describes the route where you recover your own disputes, and the platform overview describes Connect for platforms.

Sources: Chargeflow documentation for the Merchants API, Platforms API, Disputes, Accounts and platform webhook events, checked 11 October 2026.

A platform dispute also accepts optional suscripción and order objects, created_at and due_by are ISO 8601, and stage accepts Contracargo (the default), Consulta, Pre_arbitration or Arbitraje. Evidence generation only works while the dispute is in needs_response; otherwise the error is 422_dispute_invalid_state. Generation typically finishes in about 30 seconds and takes up to about 3 minutes. The Evidence-as-a-Service documentation and the platform webhook documentation hold the full references.

The platform overview lists four delivery models. Evidence-as-a-Service and Co-Branded are available today, White-Label is in beta and Alerts-as-a-Service is marked soon. Evidence-as-a-Service is for ISVs, platforms and PSPs, not for merchants of record. White-label chargeback management and embedded chargeback management compare the two heavier models, and the Chargeflow Connect launch post introduces the product. Once Alerts-as-a-Service ships, chargeback alerts are the pre-dispute layer it will cover.

For the merchant-side view of processor disputes on Stripe, Shopify and PayPal, see payment platform disputes.

Evaluate the API with realistic cases

Ask for the current schema, authentication method, supported business models, access requirements and versioning policy. Then test missing inputs, repeated requests, corrected evidence, merchant offboarding and cases close to the deadline. One clean demo case does not show production readiness, and cases blocked on missing merchant information show up in readiness and handoff metrics before they show up in request success. In-house versus outsourced chargeback management helps frame who owns each gap you find.

Preguntas frecuentes

What is a dispute API?

A dispute API is a programmatic interface that exposes dispute cases and the actions available on them, such as reading a case, submitting evidence or accepting the loss. Processor dispute APIs from Stripe, Adyen and PayPal handle case management, while evidence services assemble the response package.

How does Stripe handle disputes through its API?

Stripe creates a dispute object when a cardholder disputes a payment and sends a charge.dispute.created event. You read it with the Disputes API, submit evidence with a POST to /v1/disputes/{id} antes evidence_details.due_by, and accept the loss with /close. Evidence can typically be submitted only once.

Does a chargeback API automatically submit disputes?

No. A chargeback API submits a dispute only if it documents a submission endpoint and your account can use it. Case retrieval, evidence generation and submission are separate capabilities, and some APIs cover only one of them.

How do I submit dispute evidence through an API?

Each processor uses a different call. Stripe takes an evidence hash on the dispute update endpoint, Adyen takes documents through /supplyDefenseDocument followed by /defendDispute, and PayPal takes a multipart request to provide-evidence. Submit only after your own review step.

Where is the response deadline in each dispute API?

The deadline sits in a different field for each provider: evidence_details.due_by on Stripe, defensePeriodEndsAt in Adyen dispute webhooks and seller_response_due_date on PayPal. Store it as an absolute timestamp when the case is ingested.

Can I use an evidence API with my existing submission flow?

Yes. A hybrid model can combine partner-generated evidence with a platform's own submission flow, provided the platform defines package review, version tracking and submission ownership.

What is the difference between Chargeflow's merchant API and platforms API?

Chargeflow's merchant API lets a merchant read and enrich its own disputes and upload evidence. The platforms API lets a platform create merchant accounts, submit disputes and generate versioned evidence PDFs, and it requires a Connect account.

Evaluate dispute integration scope with Chargeflow Connect.