> ## 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, get payment requirements, 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 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.
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"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:
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"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:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"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:
```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"
}
```
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.
Configure your chains, tokens, and settlement address
See a complete request/response trace for the full purchase cycle
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.