> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# UCP merchant integration step-by-step guide

> Getting started with UCP from scratch — deploying /.well-known/ucp Profile, declaring capabilities, configuring signing keys, and phased implementation

# 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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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:

```bash theme={null}
# 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:

```javascript theme={null}
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:

```json theme={null}
{
  "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 theme={null}
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](/en/book-3/ch8-platform-integration) — Capability negotiation algorithm, extension mechanisms, and multi-platform strategies