Skip to main content
This guide walks through the three steps your merchant server must implement to accept UCP payments settled through Prism.

​
Prerequisites

  • A District Pass account
  • A Prism API key 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/payment-profile
X-API-Key: {YOUR_PRISM_API_KEY}
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/checkout-prepare
X-API-Key: {YOUR_PRISM_API_KEY}
Content-Type: application/json

{
  "amount": "12000",
  "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" }
      }
    ]
  }
}
Amounts are in token base units. The tokens that appear in accepts depend on what you have enabled in your Prism Console:
TokenDecimalsExample for $120.00
USDC6"120000000"
FDUSD18"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_API_KEY}
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
Last modified on March 23, 2026