> ## 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 a merchant, sign an x402 payment, and complete checkout in four steps.

When your agent finds a UCP merchant that supports `xyz.fd.prism_payment`, it can pay with any x402-capable wallet. This page covers the four steps: discover, checkout, sign, and complete.

## Prerequisites

* An x402-capable wallet funded on a supported chain
* A UCP profile your agent can reference (e.g., `https://platform.example/ucp/profile`)

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

## Advertise the Handler in Your Profile

Include `xyz.fd.prism_payment` in your platform's `payment_handlers` registry with `spec` and `schema`. No `config` is needed. This tells the merchant your platform can fulfill this payment method.

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "ucp": {
    "version": "2026-01-23",
    "payment_handlers": {
      "xyz.fd.prism_payment": [
        {
          "id": "prism_default",
          "version": "2026-01-23",
          "spec": "https://prism-gw.fd.xyz/ucp/prism.md",
          "schema": "https://prism-gw.fd.xyz/ucp/schema.json"
        }
      ]
    }
  }
}
```

## Payment Flow

### Step 1: Discover the Handler

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

Confirm `xyz.fd.prism_payment` appears in `payment_handlers`. If present, the merchant accepts Prism payments and the flow can proceed.

### Step 2: Create a Checkout Session

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST https://merchant.example/checkout-sessions
Content-Type: application/json
UCP-Agent: profile="https://platform.example/ucp/profile"

{
  "line_items": [
    { "item": { "id": "ticket_vip_01" }, "quantity": 1 }
  ]
}
```

The response contains `payment_handlers["xyz.fd.prism_payment"][0].config` — the x402 payment requirements populated by Prism. Extract this object; it is the direct input for wallet authorization.

### Step 3: Authorize with Your Wallet

Pass the `config` object to your x402-capable wallet as `paymentRequirements`. The wallet selects a network from `accepts`, signs an ERC-3009 authorization inside the secure enclave, and returns the complete signed payment object.

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 — no additional formatting required.

### Step 4: Complete the Checkout

Submit the wallet output as the credential. Both `instrument.type` and `credential.type` must be `"default"` — they are required UCP schema discriminators for this handler.

```http theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
POST https://merchant.example/checkout-sessions/{id}/complete
Content-Type: application/json
UCP-Agent: profile="https://platform.example/ucp/profile"

{
  "payment": {
    "instruments": [
      {
        "id": "your_instrument_id",
        "handler_id": "prism_default",
        "type": "default",
        "credential": {
          "type": "default",
          "paymentPayload": { "...": "signed ERC-3009 authorization" },
          "paymentRequirements": { "...": "config from Step 2" }
        }
      }
    ]
  }
}
```

A successful response returns a confirmed order with an on-chain transaction hash:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "order": {
    "id": "ord_abc123",
    "status": "confirmed",
    "payment": {
      "handler_id": "prism_default",
      "status": "settled",
      "transaction": "0xe80c...674b"
    }
  }
}
```

<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/ucp/flows">
    See the full purchase cycle with both sides visible
  </Card>
</CardGroup>