Merchant Integration Guide

7.1 Prerequisites

Requirement	Description	Required / Recommended
HTTPS	All endpoints must use HTTPS; Profile endpoint must not redirect (no 3xx)	Required
Domain	Own a domain where you can deploy `/.well-known/ucp`	Required
Product data	Ability to return product data in JSON format	Required
Signing keys	Generate an ES256 (P-256) key pair for Webhook signatures	Recommended
OAuth 2.0	Required for identity linking; needs an OAuth authorization server	As needed
Payment processor	At least one UCP-compatible payment processor	As needed

7.2 Step 1: Deploy the UCP Profile

The UCP Profile is the entry point through which AI agents discover your capabilities. It is served at the /.well-known/ucp path.

Profile Requirements

HTTPS only: Must be served over HTTPS. HTTP requests should return a 301 redirect to HTTPS.
No redirects: HTTPS requests to /.well-known/ucp must not return 3xx redirects. The response must be a direct 200.
Cache-Control: Must include Cache-Control: public, max-age=N where N is at least 60 seconds.
Content-Type: application/json

Minimal Profile (Product Discovery Only)

{
  "supported_versions": ["2026-04-08"],
  "services": {
    "dev.ucp.shopping": {
      "base_url": "https://mystore.com/ucp"
    }
  },
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08",
      "supported_operations": ["create", "get", "update", "complete", "cancel"]
    }
  },
  "signing_keys": []
}

Full Profile (All Capabilities)

{
  "supported_versions": ["2026-04-08"],
  "services": {
    "dev.ucp.shopping": {
      "base_url": "https://mystore.com/ucp"
    },
    "dev.ucp.common": {
      "base_url": "https://mystore.com/ucp"
    }
  },
  "capabilities": {
    "dev.ucp.shopping.checkout": {
      "version": "2026-04-08",
      "supported_operations": ["create", "get", "update", "complete", "cancel"]
    },
    "dev.ucp.common.identity_linking": {
      "version": "2026-04-08"
    },
    "dev.ucp.shopping.order": {
      "version": "2026-04-08"
    }
  },
  "payment_handlers": [
    "com.stripe.payment",
    "com.adyen.payment"
  ],
  "signing_keys": [
    {
      "kid": "key-2026-04",
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}

7.3 Generating Signing Keys

Generate an ES256 (P-256) key pair using OpenSSL:

# Generate private key
openssl ecparam -genkey -name prime256v1 -noout -out ucp-signing-key.pem

# Extract public key
openssl ec -in ucp-signing-key.pem -pubout -out ucp-signing-key-pub.pem

# Export as JWK format (requires a jose tool or programmatic conversion)
# Choose a kid that includes a date, e.g., key-2026-04

Security reminder: The private key (ucp-signing-key.pem) must be stored securely on the server. It must never appear in the Profile, source code repositories, or logs. Only the public key information (x and y coordinates) is published in the Profile’s signing_keys array.

7.4 Four-Phase Integration Path

Phase 1: Profile + Product Catalog (1 day)

The minimum viable integration. Deploy the /.well-known/ucp Profile and a product search API:

const express = require("express");
const app = express();

// UCP Profile
app.get("/.well-known/ucp", (req, res) => {
  res.set("Cache-Control", "public, max-age=3600");
  res.json({
    supported_versions: ["2026-04-08"],
    services: {
      "dev.ucp.shopping": {
        base_url: "https://mystore.com/ucp"
      }
    },
    capabilities: {
      "dev.ucp.shopping.checkout": {
        version: "2026-04-08",
        supported_operations: ["create", "get", "update", "complete", "cancel"]
      }
    },
    signing_keys: []
  });
});

// Product search
app.get("/ucp/catalog/products", async (req, res) => {
  const { query, category, limit = 10, offset = 0 } = req.query;

  const products = await db.products.search({
    query, category,
    limit: Math.min(parseInt(limit), 50),
    offset: parseInt(offset)
  });

  res.json({
    products: products.map(p => ({
      id: p.id,
      name: p.name,
      description: p.description,
      brand: p.brand,
      price: { amount: p.priceInCents, currency_code: "USD" },
      availability: p.stock > 0 ? "in_stock" : "out_of_stock",
      images: [{ url: p.imageUrl, alt: p.name }],
      url: `https://mystore.com/product/${p.slug}`
    })),
    total: products.totalCount,
    limit: parseInt(limit),
    offset: parseInt(offset)
  });
});

app.listen(3000);

Value of this phase: AI agents can discover your UCP Profile, search your catalog, and display your products to users.

Phase 2: Checkout Capability (2-3 days)

Build on Phase 1 by implementing the checkout API — five operations (Create / Get / Update / Complete / Cancel) and a six-state state machine. Requires payment processor integration. Key implementation points:

CRUD endpoints for checkout sessions
State machine transition logic
Payment processor integration (declare supported processors via payment_handlers)
ISO 4217 monetary amount handling

Phase 3: Identity Linking (2-3 days)

Implement an OAuth 2.0 authorization server:

/.well-known/oauth-authorization-server metadata endpoint
Authorization endpoint (/oauth/authorize)
Token endpoint (/oauth/token)
Revocation endpoint (/oauth/revoke), following RFC 7009
PKCE (S256) support

Phase 4: Order Management + Webhooks (2-3 days)

Order query API
Fulfillment event tracking
Adjustment operations (returns / refunds)
Webhook notifications using RFC 9421 signatures (requires publishing JWK signing keys in the Profile)

7.5 Declaring Payment Handlers in the UCP Profile

The payment_handlers array lists the payment processors you accept, using reverse-DNS naming:

{
  "payment_handlers": [
    "com.stripe.payment",
    "com.adyen.payment",
    "com.paypal.payment",
    "com.square.payment"
  ]
}

AI agents perform capability negotiation to determine mutually supported payment processors, then complete payment token exchange through a three-step lifecycle: negotiate, acquire, and complete.

7.6 HTTP Response Header Requirements

UCP endpoints should return the following HTTP headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: public, max-age=3600
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000; includeSubDomains

For the Profile endpoint (/.well-known/ucp), the Cache-Control max-age must be at least 60 seconds. A value of 3600 seconds (1 hour) is recommended.

Next chapter: Platform Integration Guide — Capability negotiation algorithm, extension mechanisms, and multi-platform strategies

UCP security model and authentication methods UCP platform integration and multi-merchant hosting

Start

Learning Paths

Getting Started with AI Commerce

OTR Open Trust Registry

UCP Universal Commerce Protocol

ACP Agentic Commerce Protocol

MCP Model Context Protocol

SEO for the AI Era

ORBEXA Integrated Solution

Templates & Prompts

Glossary

UCP merchant integration step-by-step guide

Merchant Integration Guide

7.1 Prerequisites

7.2 Step 1: Deploy the UCP Profile

Profile Requirements

Minimal Profile (Product Discovery Only)

Full Profile (All Capabilities)

7.3 Generating Signing Keys

7.4 Four-Phase Integration Path

Phase 1: Profile + Product Catalog (1 day)

Phase 2: Checkout Capability (2-3 days)

Phase 3: Identity Linking (2-3 days)

Phase 4: Order Management + Webhooks (2-3 days)

7.5 Declaring Payment Handlers in the UCP Profile

7.6 HTTP Response Header Requirements

​Merchant Integration Guide

​7.1 Prerequisites

​7.2 Step 1: Deploy the UCP Profile

​Profile Requirements

​Minimal Profile (Product Discovery Only)

​Full Profile (All Capabilities)

​7.3 Generating Signing Keys

​7.4 Four-Phase Integration Path

​Phase 1: Profile + Product Catalog (1 day)

​Phase 2: Checkout Capability (2-3 days)

​Phase 3: Identity Linking (2-3 days)

​Phase 4: Order Management + Webhooks (2-3 days)

​7.5 Declaring Payment Handlers in the UCP Profile

​7.6 HTTP Response Header Requirements

Merchant Integration Guide

7.1 Prerequisites

7.2 Step 1: Deploy the UCP Profile

Profile Requirements

Minimal Profile (Product Discovery Only)

Full Profile (All Capabilities)

7.3 Generating Signing Keys

7.4 Four-Phase Integration Path

Phase 1: Profile + Product Catalog (1 day)

Phase 2: Checkout Capability (2-3 days)

Phase 3: Identity Linking (2-3 days)

Phase 4: Order Management + Webhooks (2-3 days)

7.5 Declaring Payment Handlers in the UCP Profile

7.6 HTTP Response Header Requirements