Agent checkout needs verifiable records
What KYA actually ships today at checkout
The Problem in 30 Seconds
An agent tries to buy office supplies from a Shopify store. The merchant's fraud system sees a headless browser session, fast page transitions, and unusual checkout behavior — then blocks the order.
The merchant just rejected a legitimate purchase. The operator does not know why. The customer does not know what failed. The merchant has no clear identity record, no scoped authorization context, and no durable handle for follow-up if something breaks.
KYA does not ship a certificate lifecycle today. The live product is a simpler split: signed traces, verify recommendations, checkout-session enforcement, and pre-dispute APIs.
What KYA Actually Ships Today
The live contract
The current product surface is useful precisely because it is smaller than the old certificate story. Four pieces do the work:
Trace issuance upstream
POST /api/v1/trace/generate issues a signed trace carrying principal hash, scope, audience, and max amount.
In-band recommendation
POST /api/v1/verify resolves the agent to its operator, returns trust score and recommendation, and records a verification ID.
Checkout enforcement
POST /api/v1/checkout/sessions validates the signed trace against a delegated wallet and fails the session when scope, amount, audience, or MCC checks miss.
Pre-dispute workflows
Pre-dispute alert, rule, and evidence routes let merchants and operators open a follow-up workflow when a transaction needs review.
The Current Checkout Contract
Three calls, two merchant-edge endpoints
Operators issue traces upstream. Merchants call verify for identity and recommendation, and add checkout-session when they want trace-bound enforcement. That split matters because the handlers really do different jobs.
{
"kya_id": "kya_live_agent_123",
"transaction_context": {
"amount_cents": 4999,
"currency": "USD"
}
}{
"agent_kya_id": "kya_live_agent_123",
"trace_jwt": "<signed trace>",
"cart": {
"merchant_id": "merchant_demo_store",
"currency": "USD",
"items": [
{ "sku": "sku_123", "quantity": 1, "price_cents": 4999 }
]
},
"payment_method": {
"type": "delegated_wallet",
"wallet_id": "wallet_demo_123"
}
}The important correction: /api/v1/verify does not read the trace. It returns identity, operator context, trust score, and recommendation. Trace enforcement lives on /api/v1/checkout/sessions.
How The Pieces Fit Together
Identity, authority, enforcement, evidence
Operator issues a signed trace
The operator binds a principal hash, audience, scope, and max amount into a signed trace before checkout starts.
Merchant calls verify
Verify resolves the KYA ID, returns operator context, trust level, recommendation, reasons, and a verification ID merchants can store with the order.
Merchant opens checkout-session
Checkout-session verifies the trace, delegated wallet, amount, audience, principal binding, and merchant-category constraints before money moves.
If something goes wrong, open a follow-up workflow
Pre-dispute alerts and evidence routes can reference the same trace and verification records when merchants or operators need to escalate.
What Is Not In The Shipped Surface
Do not design against these yet
Still roadmap, not public contract
- Full certificate issuance and revocation lifecycle APIs
- Merchant SDKs or drop-in middleware across languages
- Certificate-to-payment-token binding for third-party payment rails
- A single magical verification call that does identity, recommendation, enforcement, and dispute creation by itself
Why This Still Matters
The correction here is not that KYA does less than we thought. It is that KYA does a smaller set of things more clearly than the old certificate framing suggested. That is a better product surface for merchants because each piece has a real handler behind it.
If you are wiring agent checkout today, the practical takeaway is simple: start with /api/v1/verify for identity and recommendation, add signed traces with /api/v1/trace/generate, and use /api/v1/checkout/sessions when you need the trace to fail closed at checkout.
Start With The Shipped Contract
The public docs cover the live /api/v1 surface. Build against the routes that exist today, not the certificate story we no longer claim.