Merchant Integration

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 account
A Prism Project Identify Token from the Prism Console
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:

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

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:

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

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:

{
  "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:

{
  "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, set the new object as config on the cached declaration, and return the handler 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 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:

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:

{
  "success": true,
  "transaction": "0x7a3b...0f1a",
  "network": "eip155:8453"
}

Create the order and return it with status: "completed". Use the transaction hash as payment proof:

{
  "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.

Prism Console

Configure your chains, tokens, and settlement address

End-to-End Flow

See a complete request/response trace for the full purchase cycle

Getting Started

Concepts

Architecture

Integrations

API Reference

Going to Production

AI Tooling

Resources

Prerequisites

Step 1: Host Discovery

Step 2: Build the Handler for Checkout Sessions

Fetch the Handler Declaration

Get Payment Requirements

Include in Session Response

Step 3: Handle Session Updates

Step 4: Settle via Prism

Why Prism is Simpler

Prism Console

End-to-End Flow

​Prerequisites

​Step 1: Host Discovery

​Step 2: Build the Handler for Checkout Sessions

​Fetch the Handler Declaration

​Get Payment Requirements

​Include in Session Response

​Step 3: Handle Session Updates

​Step 4: Settle via Prism

​Why Prism is Simpler

Prism Console

End-to-End Flow

Prerequisites

Step 1: Host Discovery

Step 2: Build the Handler for Checkout Sessions

Fetch the Handler Declaration

Get Payment Requirements

Include in Session Response

Step 3: Handle Session Updates

Step 4: Settle via Prism

Why Prism is Simpler