Universal Commerce Protocol Handler

Rust server that implements the Universal Commerce Protocol checkout flow and extensions

StateSet UCP Handler is a standalone Rust server that implements the Universal Commerce Protocol (UCP) checkout flow. It exposes discovery, checkout session lifecycle, tokenization, webhook delivery, and optional OAuth identity linking.

Key capabilities

• Discovery at /.well-known/ucp
• Checkout session lifecycle endpoints
• Fulfillment and discount extensions
• Order webhooks and audit logs
• Tokenization endpoints (/tokenize, /detokenize)
• Optional OAuth 2.0 identity linking and AP2 mandate extension
• gRPC API with JSON payloads
• Optional iCommerce backend with SQLite persistence

Quickstart

cargo run

The HTTP server listens on http://0.0.0.0:8081 by default. Run the demo flow:

./demo_test.sh

Required headers

By default the handler requires:

• UCP-Agent on all requests
• Request-Signature on POST and PUT

You can relax these for local testing with:

UCP_REQUIRE_UCP_AGENT=false UCP_REQUIRE_REQUEST_SIGNATURE=false cargo run

Local testing only. Request-Signature is what authenticates the caller — with UCP_REQUIRE_REQUEST_SIGNATURE=false the handler accepts writes from anyone who can reach the port, so a session can be created, mutated, or completed by an unauthenticated request. Never set either flag on a deployment that is reachable from anywhere but your own machine.

Optional headers when enabled:

• Request-Id when UCP_REQUIRE_REQUEST_ID=true
• Idempotency-Key when UCP_REQUIRE_IDEMPOTENCY=true

Create a checkout session

curl -X POST https://yourapp.com:8081/api/checkout-sessions \
  -H "UCP-Agent: profile=\"https://platform.example/profile\"" \
  -H "Request-Signature: <detached-jws>" \
  -H "Content-Type: application/json" \
  -d '{
    "line_items": [{ "item": { "id": "item_123" }, "quantity": 2 }],
    "currency": "USD"
  }'

Core endpoints

Method	Endpoint	Description
GET	/.well-known/ucp	Discovery document
GET	/api/checkout-sessions	List checkouts
POST	/api/checkout-sessions	Create checkout
GET	/api/checkout-sessions/:id	Retrieve checkout
PUT	/api/checkout-sessions/:id	Update checkout
POST	/api/checkout-sessions/:id/complete	Complete checkout
POST	/api/checkout-sessions/:id/cancel	Cancel checkout
GET	/api/orders	List orders
GET	/api/orders/:id	Retrieve order
POST	/tokenize	Tokenize credential
POST	/detokenize	Detokenize credential
GET	/metrics	Prometheus metrics
GET	/health	Health check
GET	/ready	Readiness check

Commerce backend

iCommerce is enabled by default and stores checkouts and orders in ./commerce.db. Disable it for in-memory storage:

COMMERCE_ENABLED=false cargo run

Webhooks and audit trails

Set UCP_ORDER_WEBHOOK_URL to send order events when a checkout completes. The handler also exposes:

• /api/audit-events
• /api/webhook-deliveries

OAuth and AP2 extensions

Enable identity linking with UCP_OAUTH_ENABLED=true. Enable AP2 mandate support with UCP_AP2_ENABLED=true and UCP_AP2_MERCHANT_AUTH.

gRPC access

The gRPC server listens on 0.0.0.0:50051 by default and uses JSON payloads in payload_json. Auth can be provided via authorization or x-api-key metadata.