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 definition from Prism and include it in your response:

GET https://prism-gw.fd.xyz/api/v2/merchant/ucp/handlers
X-API-Key: {YOUR_PRISM_IDENTIFY_TOKEN}

Merge the result into your UCP profile’s payment_handlers before responding to the agent:

{
  "ucp": {
    "version": "2026-01-23",
    "payment_handlers": {
      "xyz.fd.prism_payment": [
        {
          "id": "prism_default",
          "version": "2026-01-23"
        }
      ]
    }
  }
}

Step 2: Prepare Checkout via Prism

When a platform creates a checkout session (POST /checkout-sessions), call Prism to get the x402 payment requirements for that order:

POST https://prism-gw.fd.xyz/api/v2/merchant/ucp/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"
  }
}

Return the payment_handlers field from Prism’s response directly inside your checkout session response. The config field contains x402 payment requirements resolved against your Prism account:

{
  "id": "prism_default",
  "version": "2026-01-23",
  "config": {
    "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" }
      }
    ]
  }
}

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"
}

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.

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

Prerequisites

Step 1: Advertise the Handler

Step 2: Prepare Checkout via Prism

Step 3: Settle via Prism

Prism Console

End-to-End Flow

​Prerequisites

​Step 1: Advertise the Handler

​Step 2: Prepare Checkout via Prism

​Step 3: Settle via Prism

Prism Console

End-to-End Flow

Prerequisites

Step 1: Advertise the Handler

Step 2: Prepare Checkout via Prism

Step 3: Settle via Prism