README

Self-hosted UCP (Universal Commerce Protocol) endpoints for Magento 2 — AI shopping agents can discover your store, build and price checkouts, apply coupons, select shipping, pay, and track orders.

Passes the official UCP conformance suite (75 passed / 2 skipped) against Magento Open Source 2.4.7.

Self-contained — no runtime Composer dependencies, no SaaS, no credentials leaving your server.
Secure by default — disabled until you enable it; RFC 9421 HTTP Message Signatures verified on every signed request (ES256/ES384/Ed25519, raw P1363, RFC 9530 Content-Digest), with an optional strict mode requiring signatures; ES256 merchant signing keys generated automatically and stored encrypted.
Real orders — completed agent checkouts become real Magento orders through the quote pipeline, under a dedicated "UCP Agent Payment" method.

Module: Ucp_Agent · Package: ooasis/module-magento-agent Requires PHP 8.1+ (ext-openssl, ext-sodium), Magento Open Source 2.4.6+. Should work on Adobe Commerce (not yet certified).

What's implemented

Capability	Details
`/.well-known/ucp`	Business profile: services, capabilities, payment handlers, published JWKs (RFC 7638 kids) with rotation grace
Checkout sessions	Full state machine (`incomplete` → `ready_for_complete` → `completed`/`canceled`), idempotency-key replay + 409 on conflicting reuse, date-based version negotiation (422)
Discounts	Magento cart-rule coupons (percentage + fixed), sequential application, case-insensitive codes
Fulfillment	Destinations → computed options → selection with recalculated totals; known-customer address injection by buyer email
Orders	Full order entities, `GET`/`PUT /orders/{id}`, signed full-entity push webhooks (`Webhook-Id`/`Webhook-Timestamp`, retry on 5xx)
Payments	Google Pay via Stripe (direct PaymentIntent flow, no SDK); mock handler for conformance testing, only active in test mode
Multi-store	Store-view resolution by URL — prices, currency, and profile follow the requesting store

Install

composer require ooasis/module-magento-agent
bin/magento module:enable Ucp_Agent
bin/magento setup:upgrade

Then enable it: Stores → Configuration → Services → UCP Agent → Enable UCP Endpoints. Your profile is served at https://your-store.example/.well-known/ucp.

To accept unattended agent payments, add your Stripe keys under UCP Agent → Stripe; without them the Google Pay handler simply isn't advertised.

Endpoints

GET  /.well-known/ucp
POST /ucp/checkout-sessions
GET  /ucp/checkout-sessions/{id}
PUT  /ucp/checkout-sessions/{id}
POST /ucp/checkout-sessions/{id}/complete
POST /ucp/checkout-sessions/{id}/cancel
GET  /ucp/orders/{id}
PUT  /ucp/orders/{id}
POST /testing/simulate-shipping/{order_id}   (test hook, Simulation-Secret gated)

Endpoints are frontend controllers behind a lightweight router rather than webapi.xml services: RFC 9421 verification needs the raw request bytes, and the REST paths don't fit webapi routing.

Design notes & current limits

The checkout session document is protocol-native; a real Magento order is materialized through a guest quote at completion. The UCP totals the agent agreed to are authoritative for the agent-facing entities.
Shipping options come from carrier configuration (flat rate per order + free-shipping threshold). Quote-backed collectShippingRates() for real carriers (UPS, table rates) is the planned upgrade path.
Product coverage: simple and virtual products (configurable children purchasable by SKU). Bundle and downloadable products are not exposed to agents yet.
Webhook delivery retries in-request (3 attempts, backoff); queued delivery is planned for high-volume stores.
The RFC 9421 verifier ships with a standalone self-check: php dev/test_rfc9421.php (28 checks, including the RFC authors' published ECDSA test vectors).

Sibling project

The same protocol core (verifier, state machine, dual UCP+ACP support) ships for WooCommerce as UCP/ACP Agent for WooCommerce.

License

MIT

ooasis / module-magento-agent

Package info

Security

Statistics