Agentic Checkout Protocol
POST /agent/checkout/{id}/settle
Submit payment and run the acceptance gate. Returns one of accepted (200), hold (202), payment_invalid (402), or rejected (403) — and replays terminal results verbatim for idempotent retries.
Submits the rail-specific payment proof and runs the acceptance gate. Verify + policy (cheap, local) always run before any money is captured.
Request
{ "payment": { "/* rail-specific proof */": "for x402, the payment payload / tx" } }Outcomes
| Status | status | Meaning |
|---|---|---|
200 | accepted | allow Policy accepted, payment captured, receipt issued. |
202 | hold | escalate Needs human review; includes review_url + reason_codes. |
402 | payment_invalid | Payment proof bad / capture failed (safe to fix & retry). |
403 | rejected | deny Acceptance policy rejected the request. |
404 | — | Unknown session. |
409 | — | Already settled / idempotency conflict. |
410 | — | Session expired. |
200 — accepted
{
"status": "accepted",
"order_id": "…",
"receipt": "<compact JWS merchant receipt>",
"fulfillment": { "/* merchant-defined: download url, license key, shipping … */": "" }
}The receipt links to mandateRef = the buyer mandate subject. Verify it
offline.
202 — hold
{
"status": "hold",
"review_url": "https://…/review/{id}",
"reason_codes": ["REPUTATION_TOO_LOW"]
}402 / 403 — payment_invalid / rejected
Carry status + reason_codes + error_human. Common rejections:
MANDATE_REQUIRED, OVER_PER_TX_CAP,
REPUTATION_TOO_LOW, RATE_LIMITED_HOURLY.
Idempotency.
If (agent_id, idempotency_key) already produced a terminal result, the exact same
response is replayed verbatim — same status, same body. Agents may retry freely.