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.

When your agent finds an ACP merchant that supports xyz.fd.prism_payment, it can pay with any x402-capable wallet. This page covers the full flow: discover, browse, checkout, sign, and complete.

​
Prerequisites

  • An x402-capable wallet funded on a supported chain
  • An ACP client that can call merchant REST endpoints
If your platform uses the Finance District Agent Wallet, x402 signing is handled automatically by the MCP server. See Agent Wallet MCP Server.

​
Payment Flow

​
Step 1: Discover the Merchant

GET https://merchant.example/.well-known/acp.json

{
  "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"]
  }
}
Discovery does not include payment handlers. The agent won’t know if the merchant accepts xyz.fd.prism_payment until the checkout session is created.

​
Step 2: Browse the Product Feed

Fetch the merchant’s product feed (GET /product_feed) to find items. Each product has variants with IDs you’ll use at checkout.

​
Step 3: Create a Checkout Session

POST https://merchant.example/acp/api/checkout_sessions
Authorization: Bearer <agent_token>
API-Version: 2026-04-17
Idempotency-Key: cs_create_sku_red_m_1
Content-Type: application/json

{
  "line_items": [
    {
      "product_id": "prod_classic_tee",
      "variant_id": "sku_red_m",
      "quantity": 1
    }
  ]
}
The response contains capabilities.payment.handlers. Look for a handler with name: "xyz.fd.prism_payment". If status is "collecting_information", check required_fields for what’s missing and update the session.

​
Step 4: Update the Session

Provide the required fields: 
PUT https://merchant.example/acp/api/checkout_sessions/cs_001
Authorization: Bearer <agent_token>
API-Version: 2026-04-17
Idempotency-Key: cs_001_update_1
Content-Type: application/json

{
  "buyer": {
    "name": "Jane Doe",
    "email": "jane@email.com"
  },
  "shipping_address": {
    "line1": "123 Main St",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
  }
}
The response returns updated totals and an updated config in the payment handler. Continue until status is "ready_for_payment".

​
Step 5: Authorize with Your Wallet

Extract the config object from the Prism handler in the session response. Pass it directly to your x402-capable wallet as the input: 
wallet_authorize_payment({
  ...config from the handler
})
The wallet selects a network from accepts, signs an ERC-3009 authorization, and returns the complete signed payment object. The private key never leaves the wallet. The Finance District Agent Wallet handles this via its x402 authorization tool. Pass the config directly and it returns the signed object ready for submission.

​
Step 6: Complete the Checkout

Submit the wallet output as the credential. Set both instrument.type and credential.type to "default" (required by the ACP schema for this handler). The wallet output is spread into the credential object. 
POST https://merchant.example/acp/api/checkout_sessions/cs_001/complete
Authorization: Bearer <agent_token>
API-Version: 2026-04-17
Idempotency-Key: cs_001_complete_1
Content-Type: application/json

{
  "payment_data": {
    "handler_id": "x402",
    "instrument": {
      "type": "default",
      "credential": {
        "type": "default",
        ...wallet_authorize_payment output
      }
    }
  }
}
A successful response returns a confirmed order with an on-chain transaction hash: 
{
  "id": "cs_001",
  "status": "completed",
  "order": {
    "id": "ord_001",
    "checkout_session_id": "cs_001",
    "permalink_url": "https://merchant.example/orders/ord_001",
    "confirmation": {
      "confirmation_number": "0x7a3b...0f1a",
      "receipt_url": "https://basescan.org/tx/0x7a3b...0f1a"
    }
  }
}
No authentication_required response occurs with this handler. The x402 cryptographic signature serves as authentication. If the signature is invalid or the balance insufficient, the merchant returns a payment failure directly.

​
Step 7: Track the Order

Use the permalink_url or order endpoints to track fulfillment.

Commerce Payments

How Agent Wallet handles the payment signing

Agent Wallet MCP Server

Connect your agent to the Finance District wallet via MCP

End-to-End Flow

See the full purchase cycle with both sides visible
Last modified on April 29, 2026