/ pre_dispute_review
24 hours
Standard review alert. Used for scope creep, wrong-item, or duplicate-action issues that need operator attention but aren’t actively losing money.
/ PRE-DISPUTE NETWORKSide-channel for agent transactions
Catch agent disputes before they become chargebacks.
Identity verification authorizes agents before a transaction. Edge gateways enforce at the network layer. KYA Pre-Dispute Network is the KYA layer that works after an agent has acted and before the merchant has to file a chargeback. Signed-trace evidence travels with every alert; a 24-hour response SLA (2 hours for stop-loss) keeps issues from aging into formal disputes.
/ 01The interception window
Where Pre-Dispute Network sits in the stack.
Agentic commerce is converging on a layered trust stack. Identity, edge enforcement, and checkout policy all run before or at the moment of the transaction. Pre-Dispute Network covers the post-action window — the gap between an agent action and a formal chargeback.
/ L1 · Pre-transaction
Identity & attestation
Experian Agent Trust, Visa TAP, Skyfire
/ L2 · At request time
Edge enforcement
Cloudflare, network gateways
/ L3 · At authorization
Checkout policy enforcement
KnowYourAgent /api/v1/checkout/sessions
/ L4 · Post-action, before chargeback
Pre-Dispute Network
KnowYourAgent — this page
/ 02How it works
Four steps from alert to resolution.
Every alert is keyed to an X-KYA-Trace-ID, so the signed evidence chain travels with it from the moment it's opened. Operators have a clock; merchants have automation rules; both sides have an audit trail.
01
Alert raised
A merchant or operator opens a pre-dispute alert against the X-KYA-Trace-ID for the transaction. Severity is one of stop_loss (critical), review (warning), or intent_query (info), with a structured reason code from the published taxonomy.
02
Signed evidence surfaces
The signed trace, the verification record, the checkout-session policy trail, and any operator-side telemetry are attached to the alert automatically. No re-gathering, no fragmented systems.
03
Operator responds
The counterparty has 24 hours to accept, counter-offer, decline, or request more info. Stop-loss alerts compress that to 2 hours. Cryptographically attributed responses become part of the evidence chain.
04
Resolve or escalate
Matching merchant automation rules can auto-resolve configured cases as the alert is opened. Otherwise the alert remains visible against its response deadline, and unresolved cases can escalate to a formal chargeback with the signed evidence package attached.
/ 03Response SLA
A clock the operator runs against, in writing.
When a merchant opens a pre-dispute alert, the counterparty has a bounded window to respond. The response deadline is recorded on the alert; matching merchant rules can auto-resolve configured cases, while unresolved cases remain visible for review or escalation.
/ pre_dispute_stop_loss
2 hours
Critical alert: hallucination loop, principal denial, or an ongoing unauthorized action. The window is short on purpose — these need operator response or escalation fast.
/ pre_dispute_intent_query
Best effort
Informational, no SLA. Merchant clarifying operator intent — useful for ambiguous orders that don’t (yet) need a ruling.
/ 04Outcomes
Four outcomes merchants ship with the network.
Each outcome is an effect of the side-channel running, not a guaranteed metric. Volume-based numbers will land here once we have production cohorts to cite.
/ PD-01
Faster resolution
24-hour merchant-to-operator response SLA — 2 hours for stop-loss. Compare with chargeback flows that run weeks to months.
/ PD-02
Evidence already on file
Signed trace, verification record, and checkout-session policy trail attach to every alert automatically. No scramble to gather evidence after the fact.
/ PD-03
Preserved relationships
Most agent disputes are misconfiguration, not fraud. Pre-Dispute Network gives merchants and operators a structured path to resolve those cases before they become chargebacks.
/ PD-04
Defensible escalations
When an alert does need to escalate to a chargeback, the merchant arrives with a signed, time-stamped evidence package the card network can read.
/ 05Taxonomy
A published vocabulary for agent disputes.
Every alert carries a structured reason code and resolves into a structured response type. The vocabulary is public so merchants and operators can build automation rules and analytics that line up across the network.
Reason codes
HALLUCINATION_LOOPAgent stuck in repetitive, unintended behavior
SCOPE_EXCEEDEDAction falls outside the trace scope the operator issued
AMOUNT_EXCEEDEDTransaction amount above the trace cap or wallet limit
WRONG_ITEMAgent purchased something other than the principal authorized
DUPLICATE_ACTIONRepeated unintended actions on the same intent
REVOKED_DURINGAuthorization revoked mid-transaction
PRINCIPAL_DENIALEnd user denies authorizing the agent
UNAUTHORIZED_ACCESSAgent reached resources outside its authorization
OPERATOR_INITIATEDOperator self-reported the issue first
SYSTEM_DETECTEDAutomated anomaly detection flagged the action
Response types
ACCEPTEDOperator accepts the issue, agrees to remedy
COUNTER_OFFERProposes alternative resolution
DECLINEDDisputes the merchant claim
NEEDS_INFORequests additional context
AUTO_RESOLVEDMerchant rule fired before operator responded
/ 06Developer surface
API, CLI, and reference.
- POST /api/v1/pre-dispute/alerts
- GET /api/v1/pre-dispute/alerts
- POST /api/v1/pre-dispute/alerts/:id/respond
- POST /api/v1/pre-dispute/rules
- GET /api/v1/pre-dispute/evidence/:trace_id
- POST /api/v1/pre-dispute/evidence/:trace_id/verify
- kya-cli pre-dispute create
- kya-cli pre-dispute list
- kya-cli pre-dispute respond <id>
- kya-cli pre-dispute rules create
PRD-004 covers the full data model, signing, and lifecycle.
Read the docs/ 07FAQ
Pre-Dispute Network questions.
How is this different from Experian Agent Trust or Visa TAP?+
Those layers verify identity and authorize agents before a transaction, and Cloudflare enforces at the network edge. KYA Pre-Dispute Network handles a different operating window: after an agent has acted and before a merchant or operator lets the issue become a chargeback. It complements the identity stack rather than competing with it.
What is the 24h / 2h SLA, exactly?+
When a merchant opens a pre_dispute_review alert, the counterparty has 24 hours to respond with accept / counter / decline / needs_info. For pre_dispute_stop_loss alerts (critical, immediate halt requested), that window is 2 hours. Intent-query alerts are informational and do not carry a hard SLA.
What happens after the SLA window expires?+
The response deadline stays attached to the alert for merchant review and escalation. Separately, merchant-side automation rules in kya_pre_dispute_rules can auto-resolve matching alerts when they are opened, using actions such as accept, decline, counter-offer, review, refund, reverse, or hold pending review.
Does this replace chargebacks?+
No. It runs in parallel. Most agent-related disputes stem from misconfiguration, hallucinations, or scope creep — not fraud — and resolve cleanly in this side-channel. When an alert can't be resolved here, the merchant escalates to a formal chargeback with the full signed-trace evidence package attached.
Where does this live in the codebase?+
API: /api/v1/pre-dispute/alerts, /api/v1/pre-dispute/rules, /api/v1/pre-dispute/evidence/[trace_id], and /api/v1/pre-dispute/evidence/[trace_id]/verify. Storage: kya_pre_dispute_alerts and kya_pre_dispute_rules. CLI: kya-cli pre-dispute create / list / respond / rules. Reference PRD: docs/prd/PRD-004.
See the side-channel running against your own checkout.
We’ll walk through the alert lifecycle on a real trace, set up the automation rules for your reason-code policy, and stand up an operator-side response surface for the operators you transact with most.