> ## Documentation Index
> Fetch the complete documentation index at: https://developers.fd.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Merchant Integration

> Three steps to accept AI agent purchases: advertise the handler, prepare checkout, settle on-chain.

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](/overview/district-pass) account
* A Prism Project Identify Token from the [Prism Console](https://apps.fd.xyz/prism/)
* 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:

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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:

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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"` |

<Warning>
  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.
</Warning>

## 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:

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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.

<Warning>
  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.
</Warning>

<CardGroup cols={2}>
  <Card title="Prism Console" icon="sliders" href="/prism/production/console">
    Configure your chains, tokens, and settlement address
  </Card>

  <Card title="End-to-End Flow" icon="route" href="/prism/integrations/ucp/flows">
    See a complete request/response trace for the full purchase cycle
  </Card>
</CardGroup>