How to Route Every Dispute to the Right Merchant, Transaction and Evidence Source

Dispute routing ties each new dispute to one merchant, one original payment and the right evidence sources. Route from the processor account to your merchant. Then route from the processor payment to your own payment and order record. Quarantine any case that cannot reach one clear owner.

{{cta}}

Why Dispute Routing Is a Financial and Security Control

Routing looks like a simple lookup. It gets hard once you add connected accounts, split orders and shared descriptors. Migrations and reused customer data make it harder still.

A wrong match has two costs. It can show one merchant another merchant’s records. It can also post the loss to the wrong balance.

So treat the routing service like a financial control. It needs fixed keys, clear confidence states and a full audit trail.

On the API side, this is the top risk in the OWASP API Security Top 10. A request reaches a record that belongs to someone else. If you are still planning tenancy, start with a multi-tenant chargeback architecture that scopes every record to one merchant.

At a Glance: What Each Routing Layer Needs

The Routing Tree From Processor Event to Evidence

A safe router works like a tree with hard gates. Each gate must return exactly one answer. Two answers, or none, send the case to quarantine instead of the nearest guess.

Route From the Most Authoritative Identifier Outward

Start with the processor and the processor account. The same ID can exist in two namespaces, so a bare dispute or charge ID is not enough. Knowing what the acquirer and the processor each control helps you pick the right namespace.

Next, use the processor’s payment or charge ID to find your payment record and its stored route. Then resolve the merchant and order from that record.

Do not start with customer email, descriptor, amount or merchant name. Those values can help a person look into a case. They are not safe keys for who owns it. If your processors name these fields in different ways, normalize chargeback data across processors first. Then build your match rules.

Where the Routing Keys Live at Stripe and Adyen

The processor’s charge model decides which account a dispute arrives on. That changes which field holds the merchant key. Two current examples show the gap.

The lesson: write one routing rule per charge model, not one per processor. A platform that mixes direct and destination charges needs both rules. This is also where native PSP dispute tools fall short for multi-processor platforms. Each tool knows its own model, not the route across your stack.

Teams that orchestrate payments across several PSPs face this most. Store the PSP, account and charge model on every payment at authorization time, so the router never has to infer them later.

Preserve Mapping History Through Migrations

Processor accounts get swapped, merged and moved. Keep effective dates on every mapping, and never edit an old mapping in place. An old payment should still resolve to the merchant that owned it on the payment date.

Never rewrite old payments to the current processor account to tidy up reports. A dispute should follow the original route. The same rule holds when you switch chargeback providers: cases opened before the cutover keep their first owner and history.

Use a Composite Routing Key

No single ID stays reliable through every change. Combine several signals and check that they agree. When the owner is unclear, stop automated submission. A strong composite key has seven parts:

• Provider scope: processor or acquirer, connected account and merchant account set the namespace for every later ID.
• Dispute identity: the provider dispute ID and lifecycle event identify the case. Do not assume the ID is unique across providers.
• Payment identity: processor payment ID, network reference where available, amount, currency and time narrow the source payment.
• Commercial identity: merchant, seller, order, subscription and line item connect the payment to evidence.
• Version context: mapping version and effective date show how IDs changed during a migration.
• Confidence result: exact, probable, ambiguous or unmatched, with the signals stored on the decision.
• Quarantine rule: ambiguous and unmatched cases enter a review queue sorted by deadline and cannot auto-submit.

Probable matches need a policy choice. A safe default is to route them but require a person to confirm before any evidence leaves the platform.

Treat Ambiguity as a Valid System State

A missing payment or a double match should never be forced onto the nearest record. Mark the case ambiguous or missing. Attach the candidate paths. Move it to a restricted queue that only authorized staff can see.

The queue needs an internal deadline that lands well before the response due date. It also needs an escalation rule. If no one resolves the match in time, follow a written policy, such as accept the dispute or submit only what you can prove. Never let the case expire in silence.

Who carries the loss while a case sits in quarantine depends on your model. PayFacs should read who pays for PayFac chargebacks before they set the policy. Marketplaces and resellers should see how merchants of record manage chargebacks across sellers.

Resolve Evidence Only After Ownership

Once the merchant and payment are fixed, your connectors can fetch the evidence. That means the order, shipment, invoice, plan, session and support thread. Every fetched record should inherit the case’s tenant scope. Our guide on how platforms assemble chargeback evidence from orders, billing, CRM and fraud data covers the connectors.

A second match may still be needed inside the order. Split shipments, multiple service periods and order changes all need it. Tie each artifact to the disputed amount or line item. This matters most for partial chargebacks and for 3PL evidence handoffs, where the tracking number must match the disputed items.

Payment providers judge evidence by that link too. Klarna’s dispute evidence guidelines ask for evidence tied to the disputed capture, with documents linked by tracking ID or order ID. The chargeback evidence source map shows where each proof type usually lives.

{{cta}}

Implementation Sequence

Run the steps in this order. Dedupe the incoming event first with idempotent webhook handling, so retries do not create a second case.

1. Namespace the event: identify processor, environment and processor account before you read any local ID.
2. Resolve account ownership: map the processor account, as of the payment date, to your tenant and merchant.
3. Resolve the original payment: use the source payment reference and the stored route history.
4. Resolve order and service records: follow your own references from the payment record.
5. Classify the result: return matched, ambiguous, missing or conflicting, with the keys used.
6. Authorize evidence lookups: pass the resolved merchant scope to every downstream query.
7. Record and monitor: store the mapping version, matched keys, exceptions and later fixes.

Failure Modes and Controls

Monitor Routing Quality

The share of cases routed automatically is not enough on its own. Track these measures:

• Deterministic match rate
• Ambiguous and unmatched rates
• False ownership assignments
• Time spent in quarantine
• Cases near the internal deadline without a confirmed owner
• Fixes made after a case was routed

Split each measure by processor and integration. One adapter or one migration can cause a concentrated problem that a blended rate hides. Add these to the chargeback KPIs payment platforms track, and cover them when you test and monitor an embedded chargeback integration.

Some fixes come after evidence was shared or a ledger entry was posted. Those need a security and finance review, not only a data fix. Then run chargeback reconciliation on the balances it hit. For setups with many processors, the multi-processor chargeback recovery guide covers ID and webhook design in more depth.

How Chargeflow Connect Fits

Chargeflow Verbinden anchors each merchant’s disputes, evidence and integrations to a Chargeflow merchant account. When you create that account, you can store your own merchant ID in the ext_account_id field. Once you link a processor and map each of its accounts to a merchant, disputes route in on their own.

For platform-loaded disputes, send the merchant’s account_id, your PSP’s dispute ID as source_id and your transaction ID as transaction.source_id. Evidence, webhooks and outcomes then trace back to the same owner.

Not sure which delivery model fits your platform? Compare embedded, co-branded and API-based chargeback management, or start with the chargeback management for payment platforms overview.

Route every dispute and evidence request through a consistent merchant model with Chargeflow Connect.

Veelgestelde vragen

Can a Merchant Name Be Used to Route a Dispute?

No. A merchant name is not unique and can change, so it is not a safe routing key. Use it only to help an investigator after processor account, payment and order IDs fail to match.

What Happens When the Disputed Transaction Cannot Be Found?

The dispute moves to a restricted unmatched state in a quarantine queue. Keep the raw processor event, block automated submission and escalate the case before an internal deadline set ahead of the response due date.

How Should Processor Migrations Be Handled in Dispute Routing?

Keep dated processor account mappings and the original route on every payment. A dispute on an old payment then resolves to the merchant that owned it when the payment was made, not the current setup.

When Should Evidence Systems Be Queried for a Dispute?

Query evidence systems only after the platform has confirmed the tenant, merchant and payment. Every lookup should carry that merchant scope, so a search cannot return another merchant’s orders or sessions.

Which Adyen Field Links a Dispute to the Original Payment?

In Adyen dispute webhooks, originalReference holds the PSP reference of the disputed payment, and pspReference identifies the dispute itself. For some later events, such as CHARGEBACK_REVERSED, the payment reference depends on a webhook setting.

What Is the Best Metric for Dispute Routing Quality?

Deterministic match rate is the main measure of dispute routing quality. Track it with the ambiguous rate, wrong owner assignments, fixes and time in quarantine. Split each one by processor and integration.

Bronnen

• Stripe: Disputes on Connect platforms
• Stripe: Connect webhooks
• Adyen: Dispute webhooks
• Chargeflow: Onboard a merchant
• Chargeflow: Submit platform disputes
• Chargeflow Connect integrations
• Chargeflow Evidence-as-a-Service overview