Architecture

Overview

UCP architecture revolves around four core questions:

How to discover capabilities? — Profile mechanism
How to negotiate versions and capabilities? — Capability intersection algorithm
How to transmit data? — Multi-transport protocol support
How to pay securely? — Decoupled payment architecture

Discovery Mechanism

Profile Endpoints

Each participant publishes a configuration file at /.well-known/ucp:

Participant	Profile URI
Business	`https://business.example.com/.well-known/ucp`
Platform	`https://platform.example.com/profiles/shopping-agent.json`

Profile Content Structure

{
  "ucp": {
    "version": "2026-01-11",
    "services": { ... },
    "capabilities": [ ... ]
  },
  "payment": {
    "handlers": [ ... ]
  },
  "signing_keys": [ ... ]
}

Platform Declaration

Platforms declare their Profile URI in each request:

HTTP Transport:

UCP-Agent: profile="https://agent.example/profiles/shopping-agent.json"

MCP Transport:

{
  "_meta": {
    "ucp": {
      "profile": "https://agent.example/profiles/shopping-agent.json"
    }
  }
}

Negotiation Mechanism

Capability Intersection Algorithm

Input: Platform capability list, Business capability list
Output: Active capability list

Steps:
1. Calculate intersection: Keep capabilities with matching names
2. Prune orphaned extensions: Remove extensions whose parent capability is not in the intersection
3. Repeat step 2 until no capabilities are removed

Example

Platform Capabilities	Business Capabilities	Intersection Result
Checkout	Checkout, Order	Checkout
Fulfillment (extends Checkout)	Fulfillment (extends Checkout)	Fulfillment
Discount	-	- (Business doesn’t support)

Namespace Governance

Namespace Pattern	Authority	Governance
`dev.ucp.*`	ucp.dev	UCP governing body
`com.{vendor}.*`	{vendor}.com	Vendor organization
`org.{org}.*`	{org}.org	Organization

Spec URL Binding Validation

Namespace	Required Origin
`dev.ucp.*`	`https://ucp.dev/...`
`com.example.*`	`https://example.com/...`

Platforms must verify that the spec URL origin matches the namespace authority.

Transport Architecture

Transport Bindings

UCP defines transports as thin layers that only declare method names and reference underlying Schemas:

{
  "rest": {
    "schema": "https://ucp.dev/services/shopping/rest.openapi.json",
    "endpoint": "https://business.example.com/ucp/v1"
  }
}

Endpoint Resolution

OpenAPI paths are appended directly to the endpoint:

endpoint: https://business.example.com/ucp/v1
path: /checkout-sessions
result: POST https://business.example.com/ucp/v1/checkout-sessions

Transport Capability Matrix

Transport	Primary Use	Spec	Capability Mapping
REST	Standard app integration	OpenAPI 3.x	Endpoints
MCP	LLM agents	OpenRPC	Tools
A2A	Agent collaboration	Agent Card	Extensions
Embedded	Embedded business UI	OpenRPC	Events

Payment Architecture

Design Goals

Solve the N×N complexity between “platform—business—payment credential provider”:

Separate payment credentials from payment processors
Platforms don’t touch raw payment data
Support multiple payment token types

Trust Model

       ┌─────────────────┐
       │   Platform      │
       │ (no raw data)   │
       └────────┬─────────┘
                │ token/proof
                ↓
       ┌─────────────────┐
       │   Business      │
       │  (Merchant of   │
       │   Record)       │
       └────────┬─────────┘
                │
    ┌───────────┴───────────┐
    ↓                       ↓
┌─────────┐          ┌──────────────┐
│  PSP    │          │ Credential   │
│         │          │ Provider     │
└─────────┘          └──────────────┘

Payment Lifecycle

1. Negotiate → Business advertises handlers
2. Acquire → Platform executes handler logic
3. Complete → Platform submits opaque credential

Payment Handler Definition

Field	Description
`id`	Unique identifier
`name`	Handler name (reverse domain)
`version`	Version (YYYY-MM-DD)
`spec`	Spec document URL
`config_schema`	Configuration Schema URL
`instrument_schemas`	Supported payment credential types
`config`	Business-specific configuration

PCI-DSS Scope Management

Role	PCI Scope	Minimization Strategy
Platform	Avoidable	Use opaque credentials, don’t touch raw data
Business	Minimizable	Use tokenization, delegate to PCI-certified credential providers
Credential Provider	Required	Typically PCI-DSS Level 1 certified

Version Control

Version Format

Use date-based versioning: YYYY-MM-DD

Version Negotiation Rules

IF platform version ≤ business version:
    Business must handle the request
ELSE:
    Business must return version_unsupported error

Backward Compatibility

Compatible Changes (no new version needed):

Adding optional fields
Adding optional parameters
Adding new endpoints

Breaking Changes (require new version):

Removing or renaming fields
Changing field types
Making optional fields required

Security Architecture

Transport Security

All communication must use HTTPS
Requests use standard authentication (e.g., Authorization: Bearer <token>)
Webhooks must be signature-verified

Data Privacy

Sensitive data must comply with PCI-DSS and GDPR requirements; tokenization of payment data is encouraged.

Transaction Integrity (Optional)

For scenarios requiring cryptographic proof (e.g., autonomous agents), UCP supports the AP2 Mandates Extension:

Businesses provide cryptographic signatures of checkout terms
Platforms provide cryptographic proof of user authorization

Next Steps

Payment Architecture Details: Deep dive into Payment Handlers
AP2 Integration Guide: Encrypted payment instruction implementation

Core Concepts Roadmap