Stop-loss alert · critical
2 hours
For a hallucination loop, a principal denial, or an unauthorized action that is still running. The window is short on purpose.
/ KYA PRE-DISPUTE NETWORKPre-dispute for agent commerce
Catch agent disputes before they become chargebacks.
The KYA Pre-Dispute Network is where merchants and AI agent operators resolve problems with agent orders before they become chargebacks. Card-network alerts start when the buyer calls the bank. The KYA Pre-Dispute Network can start as soon as the agent acts, and it puts the agent’s operator on the other side of the case.
/ Case reviewRespond before escalation.
/ 01The agent dispute window
Agent orders go wrong before the buyer calls the bank.
An agent order can go wrong minutes after the agent acts. The buyer may not call their bank until much later. The time in between is the agent dispute window, and it is where the KYA Pre-Dispute Network works.
- 01
The agent acts
The agent places the order under the trace its operator issued.
- 02
A problem surfaces
The merchant or the operator spots a loop, an overcharge, or a complaint from the buyer.
- 03
The buyer calls the bank
Card-network pre-dispute alerts, such as Ethoca and Verifi, can start here.
- 04
A chargeback is filed
The formal dispute process takes over.
/ 02Alongside card-network alerts
A different window, a different counterparty.
Card-network pre-dispute alerts connect the issuer with the merchant once the buyer has called the bank. The KYA Pre-Dispute Network connects the merchant with the agent’s operator, earlier.
Card-network pre-dispute alertsKYA Pre-Dispute Network
Starts when
Card-network alerts
The buyer contacts their card issuer.
KYA Pre-Dispute Network
The merchant or the agent’s operator raises a problem after the agent acts.
The parties
Card-network alerts
The issuer and the merchant, through the alert provider.
KYA Pre-Dispute Network
The merchant and the agent’s operator.
Keyed to
Card-network alerts
The card transaction.
KYA Pre-Dispute Network
The order’s X-KYA-Trace-ID.
How it resolves
Card-network alerts
The merchant usually refunds to stop the chargeback. Some programs apply refund rules automatically.
KYA Pre-Dispute Network
The responder accepts, counter-offers, declines, or asks for more information. Merchant rules can resolve routine cases as the alert opens.
Ethoca is a Mastercard company and Verifi is a Visa company. They are named here for comparison only. The KYA Pre-Dispute Network does not replace card-network alerts or the chargeback process.
/ 03How it works
Four steps from alert to resolution.
Every alert is keyed to the X-KYA-Trace-IDs of the orders involved. The alert records the response deadline, merchant rules, and responses.
01
Alert raised
The merchant or the operator opens an alert against the X-KYA-Trace-IDs of the affected orders. The alert type sets the severity: stop-loss (critical), review (warning), or intent query (info). The reason code comes from the published list.
02
Evidence on the trace
From each trace, either side can retrieve linked records: scope and spending cap, operator, agent, merchant, verification result, and any payment reference. The party opening the alert can attach its own evidence, such as logs.
03
The other side responds
The responder accepts, counter-offers, declines, or asks for more information. Stop-loss alerts run on a 2-hour clock and review alerts on 24 hours. Responses attach to the alert record.
04
Resolve or escalate
Matching merchant rules can resolve routine cases as the alert opens. Otherwise the alert stays visible against its deadline, and unresolved cases can go to a formal chargeback with the trace and the response history.
/ 04Response windows
Response deadlines by alert type.
The alert type sets the response deadline, and the deadline is recorded on the alert. Merchant rules can resolve configured cases; unresolved cases stay visible for review or escalation.
Review alert · warning
24 hours
For scope creep, a wrong item, or a duplicate action that needs attention but is not actively losing money.
Intent query · info
No deadline
For an ambiguous order that does not need a ruling yet. Useful for asking what the agent was meant to do.
/ 05Outcomes
Review and respond to order problems.
Use alerts to ask for information, review a problem, and record the operator’s response.
/ PD-01
Faster resolution
Response deadlines keep merchant–operator cases moving before chargeback timelines take over.
/ PD-02
Evidence on the trace
An alert references the affected traces. Retrieve the linked records and review the evidence supplied with the alert.
/ PD-03
Preserved relationships
Some agent order problems come from misconfiguration or scope conflicts rather than fraud. The KYA Pre-Dispute Network gives merchants and operators a structured way to settle those cases before they become chargebacks.
/ PD-04
Prepared escalations
When an alert does need to escalate, the merchant brings the signed trace, the verification result, and the operator’s response history to the chargeback.
/ 06Reason codes
A published vocabulary for agent disputes.
Every alert carries a reason code and resolves into a response type. The list is public, versioned (v0.9, draft for comment), and available as JSON, so merchants and operators can build rules and reporting that line up.
Reason codes
HALLUCINATION_LOOPThe agent repeats unintended behavior, such as reordering or retrying, without new instruction.
SCOPE_EXCEEDEDThe action falls outside the scope the operator issued in the signed trace.
UNAUTHORIZED_ACCESSThe agent reached resources or account areas outside its authorization.
AMOUNT_EXCEEDEDThe transaction amount is above the trace cap or the delegated wallet limit.
WRONG_ITEMThe agent bought something other than what the principal asked for.
DUPLICATE_ACTIONThe same intent produced repeated, unintended actions.
REVOKED_DURINGAuthorization was revoked while the transaction was in progress.
PRINCIPAL_DENIALThe principal, usually the buyer, denies authorizing the agent’s action.
OPERATOR_INITIATEDThe operator reports a problem with its own agent before anyone else raises it.
SYSTEM_DETECTEDAutomated monitoring flagged the action for review.
Response types
ACCEPTEDThe responder accepts the issue and agrees to a remedy.
COUNTER_OFFERThe responder proposes a different resolution.
DECLINEDThe responder disputes the claim.
NEEDS_INFOThe responder asks for more context.
AUTO_RESOLVEDA merchant automation rule resolved the alert.
/ 07Integration
Connect the resolution flow.
POST /api/v1/pre-dispute/alerts with the agent, the affected trace IDs, a reason code, and an alert type. Attach your own evidence and an optional requested remedy.
The responder answers with accept, counter-offer, decline, or a request for more information. Routine cases can be handled by merchant rules before the timer runs out.
If the issue does not resolve, the trace’s evidence chain and the response history become the record your chargeback team works from.
Read the docs/ 08FAQ
KYA Pre-Dispute Network questions.
What is the KYA Pre-Dispute Network?
The KYA Pre-Dispute Network is a side-channel where merchants and AI agent operators resolve problems with agent orders before they become chargebacks. Each alert is keyed to the order’s X-KYA-Trace-ID, carries a reason code from a published list, and has a response window set by its alert type.
How is the KYA Pre-Dispute Network different from Ethoca or Verifi alerts?
Card-network pre-dispute alerts start when the buyer contacts their card issuer, and they connect the issuer with the merchant. The KYA Pre-Dispute Network can start as soon as the agent acts, and it connects the merchant with the agent’s operator. They cover different parts of the same timeline, so merchants can use both.
Who can open an alert?
The merchant that validated the order’s trace, or the operator that owns the agent. Either side can respond.
What are the response windows?
A stop-loss alert has a 2-hour response deadline, a review alert has 24 hours, and an intent query has no deadline. The deadline is recorded on the alert. Merchant automation rules can resolve matching alerts when they open, and an alert that passes its deadline stays visible for review or escalation.
Does the KYA Pre-Dispute Network replace chargebacks?
No. It runs alongside the chargeback process. When an alert cannot be resolved in the side-channel, the merchant can still file or contest a chargeback through the usual process, with the trace and the response history in hand.
Are the reason codes open?
Yes. The reason codes, alert types, and response types are published as a versioned list, currently v0.9 and open for comment, as a readable page and as JSON.
Next step
See the KYA Pre-Dispute Network against your own checkout.
We’ll walk through the alert lifecycle on a real trace, set up automation rules for your reason-code policy, and connect the operators you transact with most.