orcaqubits/acp-checkout-rest

ACP Checkout — REST Binding

Before writing code

Fetch live docs:

1. Fetch https://developers.openai.com/commerce/specs/checkout/ for the canonical checkout specification
2. Web-search site:github.com agentic-commerce-protocol spec openapi checkout for the latest OpenAPI YAML
3. Fetch https://developers.openai.com/commerce/guides/key-concepts/ for data model details
4. Web-search site:docs.stripe.com agentic-commerce protocol specification for Stripe's merchant-side reference

Conceptual Architecture

Five Checkout Operations

| Operation | Method | Path | Success | |-----------|--------|------|---------| | Create | POST | /checkout_sessions | 201 | | Update | POST | /checkout_sessions/{id} | 200 | | Retrieve | GET | /checkout_sessions/{id} | 200 | | Complete | POST | /checkout_sessions/{id}/complete | 200 | | Cancel | POST | /checkout_sessions/{id}/cancel | 200 |

Session State Machine

not_ready_for_payment → ready_for_payment → completed
         |                      |                |
         +──────────────────────+→ canceled ←────+
                                |
                           in_progress
                                |
                      authentication_required

The five core status enum values are: not_ready_for_payment, ready_for_payment, completed, canceled, in_progress. Note that authentication_required is a transitional/conditional state (returned during 3DS flows), not one of the five core status values.

The merchant controls status transitions. The agent reads the status and reacts.

Required Headers (Every Request)

• Authorization: Bearer <token> — REQUIRED
• API-Version: YYYY-MM-DD — REQUIRED
• Idempotency-Key: <UUID> — REQUIRED on all POST
• Content-Type: application/json

Core Data Objects

• CheckoutSession — The central primitive: ID, status, currency, line items, fulfillment options, totals, messages, links, payment provider
• Item — id + quantity (sent by agent in create/update)
• LineItem — Merchant's expanded view: base amount, discount, subtotal, tax, total, name, description, images
• Total — Typed breakdown: items_base_amount, items_discount, subtotal, discount, fulfillment, tax, fee, total
• FulfillmentOption — Shipping/digital/pickup/local delivery with pricing and windows
• Address — Buyer's fulfillment address
• Buyer — First name, last name, email, optional phone

Monetary Values

All amounts are integers in minor currency units (cents). $19.99 = 1999. Floating-point is prohibited.

Messages

The messages[] array allows merchant-to-agent communication:

• Inform the agent about restrictions, policies, or required actions
• Messages have types (info, warning, error) that influence agent behavior

Links

The links[] array provides actionable URLs with spec-defined link types:

• terms_of_use — Merchant terms of use page
• privacy_policy — Merchant privacy policy page
• seller_shop_policies — Merchant shop policies page

Create Flow

1. Agent sends items + optional buyer info + optional address
2. Merchant validates items against inventory
3. Merchant computes line items, fulfillment options, totals
4. Returns session with not_ready_for_payment or ready_for_payment

Update Flow

1. Agent sends modified items, address, fulfillment choice, or buyer info
2. Merchant revalidates and recomputes everything
3. Returns updated session with new status

Complete Flow

1. Agent sends payment data (SPT from delegated payment)
2. Merchant processes payment via PSP
3. On success: returns session with completed status + order details
4. On 3DS required: returns authentication_required + authentication challenge
5. Agent must handle 3DS and retry complete with authentication result

Error Handling

• All errors return flat objects: type, code, message, param
• Use param (JSONPath) to indicate which field caused the error
• Handle idempotency conflicts (422) and in-flight duplicates (409)

Fetch the OpenAPI spec for exact request/response schemas, field types, and all possible error codes before implementing.