> ## 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
> Accept AI agent purchases via ACP: advertise the handler, prepare checkout, settle on-chain.
Your merchant server needs to implement ACP's commerce endpoints (discovery, checkout sessions, orders) and integrate Prism for the payment handler. Prism handles token math, chain selection, and x402 formatting.
## Prerequisites
* A [District Pass](/overview/district-pass) account
* A Prism Project Identify Token from the [Prism Console](https://apps.fd.xyz/prism/)
* An ACP-compatible commerce server exposing `/.well-known/acp.json`, `/checkout_sessions`, `/product_feed`, and order endpoints
## Step 1: Host Discovery
ACP agents discover your store by fetching `GET /.well-known/acp.json`. This is a static file declaring your capabilities:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"protocol": {
"name": "acp",
"version": "2026-04-17",
"supported_versions": ["2026-04-17"]
},
"api_base_url": "https://merchant.example/acp/api",
"transports": ["rest"],
"capabilities": {
"services": ["checkout", "product_feed", "orders"],
"extensions": [],
"supported_currencies": ["usd"],
"supported_locales": ["en-US"]
}
}
```
No payment handler information is included at discovery time. Handlers are returned in the checkout session response.
## Step 2: Include the Prism Handler in Checkout Sessions
When an agent creates a checkout session (`POST /checkout_sessions`), call Prism to get the x402 payment requirements for the order and include the handler in your response.
### Call Prism
```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST https://prism-gw.fd.xyz/api/v2/merchant/acp/payment-requirements
X-API-Key: {YOUR_PRISM_IDENTIFY_TOKEN}
Content-Type: application/json
{
"amount": "19.99",
"currency": "usd",
"resource": {
"url": "https://merchant.example/acp/api/checkout_sessions/cs_001",
"description": "Purchase from Example Store"
}
}
```
### Include in Session Response
Prism returns the complete ACP handler object. Add it to `capabilities.payment.handlers[]` in your checkout session response:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"id": "cs_001",
"status": "collecting_information",
"currency": "usd",
"capabilities": {
"payment": {
"handlers": [
{
"id": "x402",
"name": "xyz.fd.prism_payment",
"version": "2026-01-15",
"spec": "https://prism-gw.fd.xyz/acp/spec.md",
"requires_delegate_payment": false,
"requires_pci_compliance": false,
"psp": "prism",
"config_schema": "https://prism-gw.fd.xyz/acp/config_schema.json",
"instrument_schemas": [
"https://prism-gw.fd.xyz/acp/instrument_schema.json"
],
"config": {
"x402Version": 2,
"resource": {
"url": "https://merchant.example/acp/api/checkout_sessions/cs_001",
"description": "Purchase from Example Store"
},
"accepts": [
{
"scheme": "exact",
"network": "eip155:56",
"amount": "19990000000000000000",
"asset": "0xaB27...b9d9",
"payTo": "0x40a0...C4fD",
"maxTimeoutSeconds": 300,
"extra": { "name": "First Digital USD", "version": "1" }
},
{
"scheme": "exact",
"network": "eip155:8453",
"amount": "19990000",
"asset": "0x036c...cf7e",
"payTo": "0x40a0...C4fD",
"maxTimeoutSeconds": 300,
"extra": { "name": "USDC", "version": "2" }
}
]
}
}
]
},
"interventions": {
"supported": [],
"required": [],
"enforcement": "conditional"
},
"extensions": []
},
"line_items": [
{
"product_id": "prod_classic_tee",
"variant_id": "sku_red_m",
"title": "Classic Tee - Red / Medium",
"quantity": 1,
"unit_price": { "amount": 1999, "currency": "usd" }
}
],
"totals": {
"subtotal": 1999,
"tax": 0,
"shipping": 0,
"total": 1999
},
"required_fields": ["buyer.name", "buyer.email", "shipping_address"]
}
```
**Request and response amounts use different units.** You send `amount` as a fiat **major-unit decimal string** (`"19.99"` — max decimals must match the currency's exponent). Prism 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 \$19.99 |
| ----- | -------- | ------------------------ |
| USDC | 6 | `"19990000"` |
| FDUSD | 18 | `"19990000000000000000"` |
The `config` must be refreshed on every session update that changes the total (e.g., after adding a shipping address or applying a discount). Re-call Prism's payment-requirements endpoint with the updated amount and return the new `config` in your response.
## Step 3: Handle Session Updates
Sessions change as the agent provides information. When the agent updates the session (`PUT /checkout_sessions/{id}`) with buyer info or a shipping address, recalculate your totals and re-fetch the Prism config with the updated amount.
Return the updated session with:
* New `totals` (including tax, shipping)
* Updated `config` in the payment handler (with amounts reflecting the new total)
* `status: "ready_for_payment"` when all required fields are present
## Step 4: Settle via Prism
When the agent completes checkout (`POST /checkout_sessions/{id}/complete`), extract `paymentPayload` and `paymentRequirements` from `payment_data.instrument.credential` (ignore the `type` fields) and forward them to Prism:
```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
{
"paymentPayload": { "..." },
"paymentRequirements": { "..." }
}
```
Prism settles on-chain and returns:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"success": true,
"transaction": "0x7a3b...0f1a",
"network": "eip155:8453"
}
```
Create the order and return it with `status: "completed"`. Use the transaction hash as payment proof:
```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
"id": "cs_x402_001",
"status": "completed",
"order": {
"id": "ord_x402_789",
"checkout_session_id": "cs_x402_001",
"permalink_url": "https://merchant.example/orders/ord_x402_789",
"confirmation": {
"confirmation_number": "0x7a3b...0f1a",
"receipt_url": "https://basescan.org/tx/0x7a3b...0f1a"
}
}
}
```
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.
## Why Prism is Simpler
| Aspect | Prism (`xyz.fd.prism_payment`) |
| -------------------- | ---------------------------------------------------------------------------------------------------------- |
| Delegate payment | Not needed. The wallet holds spending authority from the moment it's created. There's nothing to delegate. |
| PCI compliance | Not needed. No card numbers, no sensitive data touches your server. |
| Authentication (3DS) | Not needed. The x402 cryptographic signature is the authentication. |
| Settlement | Immediate settlement, no reversals. |
Configure your chains, tokens, and settlement address
See a complete request/response trace for the full purchase cycle