UCP REST API

PerfectPay's UCP shopping service gives partner agents a standard way to discover catalogs, create checkouts, and complete purchases.

Base URL Discovery

Do not hardcode the REST base URL.

Discover it from the merchant profile at:

Text

/.well-known/ucp

Use the endpoint published under:

Text

services["dev.ucp.shopping"][transport=rest].endpoint

Core Endpoints

Endpoint	Purpose
`POST /catalog/search`	Search the merchant catalog
`POST /catalog/lookup`	Resolve known catalog ids
`POST /checkout-sessions`	Create a checkout session
`GET /checkout-sessions/{id}`	Retrieve a checkout session
`POST /checkout-sessions/{id}/complete`	Place the order
`POST /checkout-sessions/{id}/cancel`	Cancel a checkout session
`GET /carts/{id}`	Retrieve a cart
`POST /carts/{id}/cancel`	Cancel a cart

Required Headers

The UCP spec uses protocol headers in addition to auth:

Header	Purpose
`UCP-Agent`	Required profile URI for the calling agent
`Authorization`	OAuth-style platform auth when used
`X-API-Key`	Reusable API key auth allocated to the platform
`Signature`	HTTP message signature
`Signature-Input`	Signature metadata
`Content-Digest`	Body digest for signed requests
`Idempotency-Key`	Required for create and complete flows
`X-Request-Id`	Request tracing

Search Example

HTTP

POST /catalog/search
UCP-Agent: profile="https://buyer.example/.well-known/ucp"
X-API-Key: partner_key_123
Signature: sig1=:base64url...:
Signature-Input: sig1=("@method" "@target-uri" "content-digest");created=1760000000
Content-Digest: sha-256=:base64url...:
Content-Type: application/json

{
  "query": "wireless headphones",
  "limit": 10
}

Checkout Example

HTTP

POST /checkout-sessions
UCP-Agent: profile="https://buyer.example/.well-known/ucp"
X-API-Key: partner_key_123
Idempotency-Key: chk_1001
Content-Type: application/json

{
  "items": [
    {
      "id": "sku_123",
      "quantity": 1
    }
  ],
  "currency_code": "USD"
}

Completion

POST /checkout-sessions/{id}/complete is the order placement step and uses the same protocol headers, including Idempotency-Key.