Skip to main content

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.

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 API key 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_API_KEY}
Content-Type: application/json

{
  "amount": "1999",
  "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"]
}
Amounts are in token base units. The tokens that appear in accepts depend on what you have enabled in your Prism Console:
TokenDecimalsExample for $19.99
USDC6"19990000"
FDUSD18"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_API_KEY}
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

AspectPrism (xyz.fd.prism_payment)
Delegate paymentNot needed. The wallet holds spending authority from the moment it’s created. There’s nothing to delegate.
PCI complianceNot needed. No card numbers, no sensitive data touches your server.
Authentication (3DS)Not needed. The x402 cryptographic signature is the authentication.
SettlementImmediate 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
Last modified on April 29, 2026