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

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:

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

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

Prerequisites

Step 1: Host Discovery

Step 2: Include the Prism Handler in Checkout Sessions

Call Prism

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: Include the Prism Handler in Checkout Sessions

​Call Prism

​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: Include the Prism Handler in Checkout Sessions

Call Prism

Include in Session Response

Step 3: Handle Session Updates

Step 4: Settle via Prism

Why Prism is Simpler