Skill: ichiorca/ucp-checkout-rest (version 1.0.0)

--- name: ucp-checkout-rest description: > Implement UCP Checkout over the REST binding — create, get, update, complete, and cancel checkout sessions with proper headers, idempotency, status transitions, and error handling. Use when building REST-based UCP checkout endpoints or clients. --- # UCP Checkout — REST Binding ## Before writing code **Fetch live spec**: Web-search `site:ucp.dev specification checkout-rest` and fetch the page for the exact current endpoint shapes, required headers, request/response schemas, and status codes. Also fetch https://ucp.dev/specification/reference/ for all data type definitions (Buyer, LineItem, Total, Message, etc.). ## Conceptual Architecture ### Five REST Operations | Operation | HTTP | Path | Idempotent? | |-----------|------|------|-------------| | Create Checkout | POST | `/checkout-sessions` | Yes (via Idempotency-Key) | | Get Checkout | GET | `/checkout-sessions/{id}` | Naturally | | Update Checkout | PUT | `/checkout-sessions/{id}` | Yes (full replace) | | Complete Checkout | POST | `/checkout-sessions/{id}/complete` | Yes (via Idempotency-Key) | | Cancel Checkout | POST | `/checkout-sessions/{id}/cancel` | Yes (via Idempotency-Key) | ### Required Headers (every request) - `UCP-Agent`: Platform's profile URI in RFC 8941 structured field format — `profile="https://..."` - `Idempotency-Key`: UUID for mutating operations; Business caches 24+ hours - `Request-Id`: UUID for distributed tracing - `Request-Signature`: Cryptographic signature for request integrity verification - `Content-Type`: `application/json` ### Status State Machine ``` incomplete → requires_escalation → ready_for_complete → complete_in_progress → completed | | | | +---------------+--------------------+----------------------+--------→ canceled ``` The `canceled` state is reachable from any non-terminal state (incomplete, requires_escalation, ready_for_complete, complete_in_progress). The agent's job is to drive the session from `incomplete` to `ready_for_complete` by resolving messages, then call complete. ### Negotiation in Every Response Every response includes a `ucp` object with the negotiated version and capabilities. The Business computes the intersection of its own capabilities with the Platform's profile, prunes orphaned extensions, and returns only what both sides support. ### Error Handling Pattern Responses include a `messages` array. Each message has: - `type`: error / warning / info - `code`: Machine-readable error code - `content`: Human-readable description - `severity`: recoverable / requires_buyer_input / requires_buyer_review (these are the 3 formal enum values; note: `escalation` appears in some spec sections but is NOT part of the formal severity enum — this is a spec inconsistency) - `path`: JSONPath pointing to the problematic field **Agent behavior by severity:** - `recoverable` → Agent fixes automatically (e.g., update with missing address) - `requires_buyer_input` → Ask the human user - `requires_buyer_review` → Show totals/terms for human confirmation - `escalation` → Redirect to `continue_url` ### Implementation Checklist **Business (merchant server):** 1. Parse `UCP-Agent` header and fetch platform profile for negotiation 2. Validate `Idempotency-Key` — return cached response if duplicate 3. Create checkout session with line items, compute totals 4. Return negotiated `ucp` object + full session state + messages 5. Handle Update by recalculating totals, re-validating, updating messages 6. Handle Complete by processing payment credential, creating order 7. Handle Cancel by cleaning up session 8. Return proper HTTP status codes (201 Created, 200 OK, 400/409/429, etc.) **Platform (agent client):** 1. Discover Business profile at `/.well-known/ucp` 2. Send `UCP-Agent` header with own profile URI 3. Create checkout, inspect `status` and `messages` 4. Loop: resolve messages → update checkout → re-check status 5. When `ready_for_complete`: acquire payment credential, call complete 6. Handle `requires_escalation` by surfacing `continue_url` to user ### Monetary Values All amounts are **integers in minor currency units** (e.g., $29.99 = `2999`). Never use floating point. ### TLS Requirement All UCP REST endpoints MUST be served over HTTPS with minimum TLS 1.3.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector:  ()