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.

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

Prism Console

End-to-End Flow

​Prerequisites

​Step 1: Advertise the Handler

​Step 2: Get Payment Requirements from Prism

​Step 3: Settle via Prism

Prism Console

End-to-End Flow

Prerequisites

Step 1: Advertise the Handler

Step 2: Get Payment Requirements from Prism

Step 3: Settle via Prism