> ## 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.

# Agent Integration

> Discover an ACP merchant, sign an x402 payment, and complete checkout.

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](/agent-wallet/ai-integration/mcp-server).

## Payment Flow

### Step 1: Discover the Merchant

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
GET https://merchant.example/.well-known/acp.json
```

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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"]
  }
}
```

<Note>
  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.
</Note>

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

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
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:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "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"
    }
  }
}
```

<Note>
  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.
</Note>

### Step 7: Track the Order

Use the `permalink_url` or order endpoints to track fulfillment.

<CardGroup cols={2}>
  <Card title="Commerce Payments" icon="wallet" href="/agent-wallet/concepts/commerce">
    How Agent Wallet handles the payment signing
  </Card>

  <Card title="Agent Wallet MCP Server" icon="plug" href="/agent-wallet/ai-integration/mcp-server">
    Connect your agent to the Finance District wallet via MCP
  </Card>

  <Card title="End-to-End Flow" icon="route" href="/prism/integrations/acp/flows">
    See the full purchase cycle with both sides visible
  </Card>
</CardGroup>