> ## 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: Build the Handler for Checkout Sessions

When an agent creates a checkout session (`POST /checkout_sessions`), you build the Prism handler from two Prism calls: the handler declaration and the payment requirements.

### Fetch the Handler Declaration

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET https://prism-gw.fd.xyz/api/v2/merchant/acp/handlers
X-API-Key: {YOUR_PRISM_IDENTIFY_TOKEN}
```

Unlike the UCP handlers route, this one needs the API key. Cache the declaration; it rarely changes. It is the handler with an empty `config`:

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

### Get Payment Requirements

```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": "19.99",
  "currency": "usd",
  "resource": {
    "url": "https://merchant.example/acp/api/checkout_sessions/cs_001",
    "description": "Purchase from Example Store"
  }
}
```

Prism returns the raw x402 PaymentRequired object, with no wrapper. The call is the same for UCP and ACP:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "x402Version": 2,
  "resource": {
    "url": "https://merchant.example/acp/api/checkout_sessions/cs_001",
    "description": "Purchase from Example Store"
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "19990000",
      "asset": "0x036c...cf7e",
      "payTo": "0x40a0...C4fD",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USDC", "version": "2" }
    }
  ]
}
```

### Include in Session Response

Build the handler yourself: copy the cached declaration and set `config` to the x402 object above (`{ ...declaration, config }`). Do not change any other field. Add the result 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"` |

<Warning>
  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, set the new object as `config` on the cached declaration, and return the handler in your response.
</Warning>

## 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 call Prism payment requirements again 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"
    }
  }
}
```

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

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

<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/acp/flows">
    See a complete request/response trace for the full purchase cycle
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.