Merchant Integration

Your merchant server needs three things to accept UCP payments through Prism: a discovery endpoint, a checkout call, and a settle call. Everything else (token math, chain selection, x402 formatting) is handled by Prism.

Prerequisites

A District Pass account
A Prism Project Identify Token from the Prism Console
A UCP-compatible commerce server exposing /.well-known/ucp, /checkout-sessions, and order endpoints

Step 1: Advertise the Handler

When a UCP agent calls GET /.well-known/ucp, fetch the handler declaration for your UCP version from Prism and include it in your response. The route is public and needs no API key. Cache the declaration; it rarely changes.

GET https://prism-gw.fd.xyz/ucp/2026-08-25/handlers

Merge the result into your UCP profile’s payment_handlers before responding to the agent. Add the entry as Prism returns it; do not change its fields:

{
  "ucp": {
    "version": "2026-08-25",
    "payment_handlers": {
      "xyz.fd.prism_payment": [
        {
          "id": "xyz.fd.prism_payment",
          "version": "2026-10-07",
          "spec": "https://prism-gw.fd.xyz/ucp/prism.md",
          "schema": "https://prism-gw.fd.xyz/ucp/schema.json",
          "available_instruments": [{ "type": "x402" }],
          "config": {}
        }
      ]
    }
  }
}

Step 2: Get Payment Requirements from Prism

When a platform creates a checkout session (POST /checkout-sessions), call Prism to get the x402 payment requirements for that order. This call does not depend on the UCP version:

POST https://prism-gw.fd.xyz/api/v2/merchant/payment-requirements
X-API-Key: {YOUR_PRISM_IDENTIFY_TOKEN}
Content-Type: application/json

{
  "amount": "120.00",
  "currency": "USD",
  "resource": {
    "url": "https://merchant.example/checkout-sessions/sess_abc123",
    "description": "Coldplay World Tour - Floor Standing GA"
  }
}

Prism returns the raw x402 PaymentRequired object, with no wrapper:

{
  "x402Version": 2,
  "resource": {
    "url": "https://merchant.example/checkout-sessions/sess_abc123",
    "description": "Coldplay World Tour - Floor Standing GA"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:56",
      "amount": "120000000000000000000",
      "asset": "0xaB27f55DB008704Ed8098f0dfBCf5e1aA387b9d9",
      "payTo": "0x40a01003f7543a3a3ee64fFB05504173BDb1C4fD",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "First Digital USD", "version": "1" }
    },
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "120000000",
      "asset": "0x036cbd53842c5426634e7929541ec2318f3dcf7e",
      "payTo": "0x40a01003f7543a3a3ee64fFB05504173BDb1C4fD",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}

Build the checkout entry yourself. Take id and version from the cached handlers declaration. Set config to the object above. Put the entry in payment_handlers of your checkout session response:

{
  "xyz.fd.prism_payment": [
    {
      "id": "xyz.fd.prism_payment",
      "version": "2026-10-07",
      "config": {
        "x402Version": 2,
        "resource": { "url": "https://merchant.example/checkout-sessions/sess_abc123" },
        "accepts": ["..."]
      }
    }
  ]
}

Request and response amounts use different units. You send amount as a fiat major-unit decimal string ("120.00" for $120.00 — max decimals must match the currency’s exponent, so USD allows 2). Prism converts it and returns the accepts[].amount values in token base units. The tokens that appear in accepts depend on what you have enabled in your Prism Console:

Token	Decimals	Example for $120.00
USDC	6	`"120000000"`
FDUSD	18	`"120000000000000000000"`

UCP requires payments to be bound to the specific product or service being purchased. Set resource.url to the unique checkout session URL. The agent wallet includes this URL in the signed authorization, tying the credential to that session.

Step 3: Settle via Prism

When the platform completes checkout (POST /checkout-sessions/{id}/complete), extract the credential from payment.instruments[0].credential and forward it to Prism’s settlement endpoint:

POST https://prism-gw.fd.xyz/api/v2/payment/settle
X-API-Key: {YOUR_PRISM_IDENTIFY_TOKEN}
Content-Type: application/json

{ ...entire credential object from the platform... }

Prism settles on-chain and returns:

{
  "success": true,
  "transaction": "0xe80c...674b",
  "network": "eip155:56"
}

Before you settle, check that the instrument has handler_id xyz.fd.prism_payment, type x402, and credential.type x402. Reject any other value with a UCP error and do not create an order. The extra type field in the credential is safe to forward; Prism ignores it. Return the confirmed order to the platform with payment.status: "settled" and payment.transaction set to the returned txHash.

Do not call the settle endpoint more than once per checkout session. If a complete request arrives for an already-settled session, return the previous order without re-submitting to Prism.

Authenticate Platforms

Discovery, catalog search, and catalog lookup are public in every mode. Every other route identifies the calling platform by the profile URL in UCP-Agent. A platform proves that profile with an RFC 9421 signature that verifies against the keys[] of the profile, or with an API key you registered for the profile. One store key per merchant. ACP presents it as Authorization: Bearer. UCP presents it as X-API-Key.

WooCommerce

Open WooCommerce > Settings > Advanced > UCP versions. The Platform access block has a mode selector and the list of registered platforms.

Mode	Behavior
Open (default)	Any platform can shop. A platform registered in the list must send its key or sign, otherwise it gets `401 signature_missing`. A platform that is not registered and sends no credential is served as unverified.
Authenticated	Every platform must sign its requests or send a registered key. A request with no credential gets `401 signature_missing`.
Registered only	Only platforms with an enabled entry in the list are served, signed or with their key. Any other platform gets `403 profile_not_trusted`.

In every mode a presented credential is always checked. A wrong or unknown X-API-Key gets 401 key_not_found. A request that carries a Signature or Signature-Input header is checked as a signed request and rejected if the signature fails. Neither falls through to unverified.

Open does not protect carts, checkout sessions, or orders of platforms that send no key. Those callers share ownership per claimed profile URL: anyone who claims the same profile URL reaches the same records. Only the unguessable ids and the Idempotency-Key the client chooses keep them apart. Someone who claims the same URL and knows an Idempotency-Key and the same create body gets the existing session back, and a different body gets 409 idempotency_key_conflict. Near-identical URLs (other path case, percent-encoding, a trailing dot in the host, a query string) map to separate unverified spaces. Turn on Authenticated or Registered only if the store holds sensitive buyer data. Register a platform to give it a private space that only its key can reach.

Register a platform

Enter the platform’s https profile URL (at most 180 characters) and a label, then save.
Copy the API key shown in the notice after saving.
Give the key to the platform operator. The platform sends it as X-API-Key next to its UCP-Agent header. For the Finance District MCP server, the operator sets it as Merchants:<name>:ApiKey.

A key grants the identity of the profile URL it is registered for, so register only profile URLs you have confirmed belong to the platform you are onboarding. A key presented with a different profile URL answers 403 profile_not_trusted. Registering a platform that used to shop without a key starts a new private space. What it created before registering is no longer reachable by it.

Show a key again

Tick Show on the platform’s row and save. The key appears once in the notice after saving. It is not printed in the page, in logs, or in REST responses.

The store keeps the key hash for verification and an encrypted copy so it can be shown again.
Only users with the manage_woocommerce capability can reveal a key. Each reveal is written to WooCommerce > Status > Logs (source fd-ucp) with the platform profile and user id, never the key.
A key that cannot be shown must be re-issued: register the profile again to get a new key, then disable the old one. This applies to keys issued before the Show option existed and to keys whose encrypted copy can no longer be read, for example after the WordPress salts change. The old key keeps working until you disable it.
Anyone who holds a database dump together with wp-config.php can decrypt the stored copies. Rotate the key if either leaks.

Disable or revoke a platform

You can disable or delete a platform at any time. To revoke a platform, disable all of its entries. The store then refuses that platform with 403 profile_not_trusted on both the signed and the API key path. A platform with at least one enabled entry is not blocked, so you can rotate a key by adding a new one and disabling the old one. Deleting the entries removes the block. In Open mode a revoked or unregistered platform can still come back as unverified under a different or near-identical profile URL. Use Authenticated or Registered only when this matters. Carts, checkout sessions, and orders belong to the platform that created them. Another platform that asks for them gets 404 with the route’s own not-found code, for example order_not_found.

Saleor

UCP routes stay open when no X-API-Key is sent. A request that sends X-API-Key must send the store’s ACP key, otherwise it gets 401 key_not_found, including when the store has no ACP key set. The integration does not check request signatures. Orders require the UCP-Session-Secret header returned when the checkout session is created. Checkout sessions are protected only by their id, not by the platform profile. See Agent Integration for every error code.

Prism Console

Configure your chains, tokens, and settlement address

End-to-End Flow

See a complete request/response trace for the full purchase cycle

Getting Started

Concepts

Architecture

Integrations

API Reference

Going to Production

AI Tooling

Resources

Prerequisites

Step 1: Advertise the Handler

Step 2: Get Payment Requirements from Prism

Step 3: Settle via Prism

Authenticate Platforms

WooCommerce

Register a platform

Show a key again

Disable or revoke a platform

Saleor

Prism Console

End-to-End Flow

​Prerequisites

​Step 1: Advertise the Handler

​Step 2: Get Payment Requirements from Prism

​Step 3: Settle via Prism

​Authenticate Platforms

​WooCommerce

​Register a platform

​Show a key again

​Disable or revoke a platform

​Saleor

Prism Console

End-to-End Flow

Prerequisites

Step 1: Advertise the Handler

Step 2: Get Payment Requirements from Prism

Step 3: Settle via Prism

Authenticate Platforms

WooCommerce

Register a platform

Show a key again

Disable or revoke a platform

Saleor