Skip to main content
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
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

MethodEndpointDescription
GET/.well-known/ucpDiscovery document
GET/api/checkout-sessionsList checkouts
POST/api/checkout-sessionsCreate checkout
GET/api/checkout-sessions/:idRetrieve checkout
PUT/api/checkout-sessions/:idUpdate checkout
POST/api/checkout-sessions/:id/completeComplete checkout
POST/api/checkout-sessions/:id/cancelCancel checkout
GET/api/ordersList orders
GET/api/orders/:idRetrieve order
POST/tokenizeTokenize credential
POST/detokenizeDetokenize credential
GET/metricsPrometheus metrics
GET/healthHealth check
GET/readyReadiness 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.