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.

Agentic Commerce Protocol (ACP) is an open standard by OpenAI that defines a full commerce journey for AI agents: discovery, product feeds, cart, checkout, payment, and order lifecycle. Prism plugs in as a payment handler (xyz.fd.prism_payment), settling payments on-chain with stablecoins for any ACP-compatible merchant.

​
How Prism Fits Into ACP

ACP supports multiple payment handlers per merchant (cards via Stripe, wallets, etc.). Prism contributes one: xyz.fd.prism_payment, which uses x402 under the hood. Unlike ACP’s card-based handlers, Prism requires no delegate payment step and no PCI compliance. Prism does three things:
  1. Handler definition — Prism returns a complete, ready-to-use handler object for your checkout session responses. Chains, tokens, and settlement addresses are managed in the Prism Console.
  2. Payment requirements — At checkout, Prism returns x402 payment requirements with the correct token amounts and contract addresses already resolved. When the x402 spec evolves, Prism generates the new format.
  3. Settlement — The merchant forwards the agent’s signed credential to Prism. Prism verifies it, executes the on-chain transfer, and returns the transaction hash.

​
The Payment Flow

​
Merchant Integration

​
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: Advertise at Checkout

When an agent creates a checkout session (POST /checkout_sessions), your server calls Prism to get the x402 payment requirements for the order and includes the handler in the session response: 
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_x402_001",
    "description": "Classic Tee - Red / Medium"
  }
}
Prism returns the complete ACP handler object. Add it to capabilities.payment.handlers[] in your checkout session response: 
{
  "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_x402_001",
      "description": "Classic Tee - Red / Medium"
    },
    "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" }
      }
    ]
  }
}
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"
When the checkout total changes (e.g., after adding a shipping address or applying a discount), call Prism again with the new amount. The config.accepts amounts must always reflect the current session total.

​
Step 2: Settle via Prism

When the agent completes checkout (POST /checkout_sessions/{id}/complete), extract paymentPayload and paymentRequirements from the credential 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"
}
Return the confirmed order with the transaction hash as payment proof. Use the tx hash as confirmation_number and a block explorer link as receipt_url.
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.

​
Agent Integration

Agents purchasing from ACP merchants via this handler need an x402-capable wallet. The agent extracts config from the handler in the checkout session response and passes it directly to the wallet for signing. No delegate payment call is needed. See the Agent guide for the full flow.
Last modified on April 29, 2026