UCP Architecture

UCP is not a single API. It is a layered, decentralized protocol stack that standardizes how AI agents interact with merchant backends. This page explains the architecture in practical terms.

Protocol Layers

UCP separates concerns into distinct layers. Each layer handles a specific responsibility:

Transport Layer

UCP supports four transports. The same business logic can be exposed through multiple transports simultaneously. Merchants choose which to support; agents choose which to use.

POST /checkout-sessions
GET /checkout-sessions/{id}
PUT /checkout-sessions/{id}
POST /checkout-sessions/{id}/complete

POST /mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "checkout/create",
  "params": {
    "meta": {
      "ucp-agent": {
        "profile": "https://..."
      }
    }
  }
}

Trust Model

UCP introduces a trust framework designed for agentic commerce, where the agent is an intermediary between buyer and merchant.

Agent Profiles

Agents define a profile so merchants can verify them and apply the right rate limits and tool access. Higher trust tiers unlock broader access, including direct checkout completion. Profiles are hosted at a well-known URL and referenced on every UCP request.

// REST: profile in header
UCP-Agent: profile="https://agent.example/profile"

// MCP: profile in params
{
  "meta": {
    "ucp-agent": {
      "profile": "https://agent.example/profile"
    }
  }
}

Identity Linking

UCP uses OAuth 2.0 for secure, authorized relationships between agents and merchants. Agents do not share user credentials. Instead, they obtain scoped tokens:

// Merchant's OAuth config at /.well-known/oauth-authorization-server
{
  "issuer": "https://shop.example.com",
  "authorization_endpoint": "https://shop.example.com/oauth2/authorize",
  "token_endpoint": "https://shop.example.com/oauth2/token",
  "scopes_supported": [
    "dev.ucp.shopping.checkout",
    "dev.ucp.shopping.order:read",
    "dev.ucp.shopping.order:manage"
  ],
  "grant_types_supported": ["authorization_code", "refresh_token"]
}

Payment Trust

Every payment authorization is backed by cryptographic proof of user consent via AP2 payment mandates and verifiable credentials. This solves the "rogue agent" problem - an agent cannot complete a payment without provable user authorization.

Discovery Flow

Here is what happens when an agent first encounters a merchant:

1. Agent fetches https://merchant.com/.well-known/ucp
2. Response contains the merchant's UCP profile: version, services, capabilities, payment handlers
3. Agent caches the profile (both parties can cache)
4. Agent checks protocol version compatibility
5. If versions match, proceed to negotiation. If not, check supported_versions for a compatible profile

GET https://shop.example.com/.well-known/ucp
Accept: application/json

// Response:
{
  "ucp": {
    "version": "2026-04-08",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "2026-04-08",
          "transport": "rest",
          "endpoint": "https://shop.example.com/ucp/v1",
          "schema": "https://ucp.dev/.../rest.openapi.json"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [...],
      "dev.ucp.shopping.fulfillment": [...]
    },
    "payment_handlers": { ... }
  }
}

Capability Negotiation Flow

1. Agent sends its profile URL with the request
2. Merchant fetches (or uses cached) agent profile
3. Merchant computes intersection of agent capabilities and merchant capabilities
4. Merchant selects the active capability set (server-selects)
5. For each active extension, merchant checks requires constraints
6. Incompatible extensions are excluded; orphaned extensions are re-pruned
7. Merchant responds with the negotiated capability set

Checkout Lifecycle

The checkout session moves through defined states:

// 1. Create checkout from cart
POST /checkout-sessions
{
  "line_items": [{"product_id": "123", "quantity": 1}]
}
// Response: status = "incomplete"

// 2. Update checkout (add buyer info, fulfillment, etc.)
PUT /checkout-sessions/{id}
{
  "buyer": { "email": "user@example.com", ... },
  "fulfillment": { "methods": [...] }
}
// Response: status = "ready_for_complete"

// 3. Complete checkout (submit payment)
POST /checkout-sessions/{id}/complete
{
  "payment": { "instrument": {...}, "credential": "..." }
}
// Response: status = "completed" OR "requires_escalation"

// 4. If escalation needed:
// Response includes continue_url for buyer to finalize in browser
// Agent can resume after buyer completes the step

// 5. Cancel if needed
DELETE /checkout-sessions/{id}

Payment Architecture

UCP delegates payments to AP2 (Agent Payments Protocol). The key architectural decision is separating instruments from handlers:

• Payment instruments - what the consumer uses to pay (cards, wallets, bank transfers, stablecoins)
• Payment handlers - the processors that execute the payment (Stripe, Adyen, Braintree, etc.)

This separation means UCP is payment-agnostic. Any processor, any wallet. The merchant declares which handlers they support in their profile. The agent and merchant negotiate which to use. Payment handlers process the actual transaction using the merchant's existing payment infrastructure.

Escalation

Not every transaction can be completed by an agent autonomously. UCP defines a clean escalation path:

1. Agent attempts to complete checkout
2. Merchant determines human input is needed (3DS, address selection, final-sale confirmation, etc.)
3. Merchant returns status: "requires_escalation" with a continue_url
4. Agent presents the continue_url to the buyer
5. Buyer opens the URL in their browser and completes the required step
6. Agent can resume the checkout or receive a webhook when done