Agent Integration

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)
A way to authenticate: request signing with a key in your profile, or an API key from the merchant when the store requires one

If your platform uses the Finance District Agent Wallet, x402 signing is handled automatically by the MCP server. See Agent Wallet MCP Server.

Advertise the Handler in Your Profile

Include xyz.fd.prism_payment in your platform’s payment_handlers registry. Use the same entry Prism publishes, with an empty config. This tells the merchant your platform can fulfill this payment method.

{
  "ucp": {
    "version": "2026-08-25",
    "payment_handlers": {
      "xyz.fd.prism_payment": [
        {
          "id": "xyz.fd.prism_payment",
          "version": "2026-10-07",
          "spec": "https://prism-gw.fd.xyz/ucp/prism.md",
          "schema": "https://prism-gw.fd.xyz/ucp/schema.json",
          "available_instruments": [{ "type": "x402" }],
          "config": {}
        }
      ]
    }
  }
}

The entry schema is the handler config schema. The instrument schema is linked from that document at $defs["xyz.fd.prism_payment"].instrument.

Authentication

Discovery (GET /.well-known/ucp), catalog search, and catalog lookup need no credentials. Every other request carries UCP-Agent: profile="https://..." with the https URL of your platform profile. Depending on the store, you also prove that profile in one of two ways:

Signed requests. Sign each request with RFC 9421 HTTP message signatures. Publish the public key in the keys[] of the profile named in UCP-Agent. The store verifies the signature against that profile.
API key. Ask the merchant for an API key registered for your profile URL. Send it in the X-API-Key header together with UCP-Agent. The key only works for the profile URL the merchant registered it for.

POST https://merchant.example/checkout-sessions
Content-Type: application/json
UCP-Agent: profile="https://platform.example/ucp/profile"
X-API-Key: {KEY_ISSUED_BY_THE_MERCHANT}

What a store requires depends on its access mode:

Store mode	Without a credential	With a credential
Open (default)	Served, unless your profile is registered at the store. A registered profile gets `401 signature_missing`.	Always checked. A wrong key gets `401 key_not_found`.
Authenticated	`401 signature_missing`	Must be a valid signature or a registered key.
Registered only	`403 profile_not_trusted` if your profile is not registered. A registered profile gets `401 signature_missing`.	Must be a registered key, or a signature from a registered profile.

In Open mode a platform that sends no credential is identified only by the profile URL it claims, and platforms that claim the same URL share the same carts, checkout sessions, and orders. Ask the merchant for a key to get a private space. Once the merchant registers your profile, send the key on every request. The verified profile URL identifies your platform. On WooCommerce, checkout sessions, carts, and orders belong to the platform that created them. A request for a session, cart, or order that belongs to another platform answers 404 with the route’s own not-found code, for example order_not_found. Orders are addressed by an opaque id such as wc_order_..., and there is no endpoint that lists orders. On Saleor, a sent X-API-Key must equal the store’s ACP key, orders require the UCP-Session-Secret header returned when the checkout session is created, and checkout sessions are protected by their id.

Status	Code	Meaning
400	`invalid_profile_url`	`UCP-Agent` is missing or does not carry an https profile URL of at most 180 characters
401	`signature_missing`	The request has neither a signature nor an `X-API-Key`, and the store requires one: the store is in Authenticated mode, or your profile is registered at the store
401	`key_not_found`	The `X-API-Key` is not registered, is disabled, or does not equal the store key, or the signing key id is not in the profile `keys[]`
401	`signature_invalid`	The signature does not verify, its required components are missing, or only one of `Signature` and `Signature-Input` is sent
403	`profile_not_trusted`	The `X-API-Key` is registered for a different profile than the one in `UCP-Agent`, the merchant disabled your platform, or the store accepts registered platforms only and yours is not registered
424	`profile_unreachable`	The store could not fetch your profile to verify the signature

Payment Flow

Step 1: Discover the Handler

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

POST https://merchant.example/checkout-sessions
Content-Type: application/json
UCP-Agent: profile="https://platform.example/ucp/profile"
X-API-Key: {KEY_ISSUED_BY_THE_MERCHANT}

{
  "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 "x402". The credential is the wallet output plus that one type field. Set handler_id to xyz.fd.prism_payment and give the instrument an id.

POST https://merchant.example/checkout-sessions/{id}/complete
Content-Type: application/json
UCP-Agent: profile="https://platform.example/ucp/profile"
X-API-Key: {KEY_ISSUED_BY_THE_MERCHANT}

{
  "payment": {
    "instruments": [
      {
        "id": "your_instrument_id",
        "handler_id": "xyz.fd.prism_payment",
        "type": "x402",
        "credential": {
          "type": "x402",
          "x402Version": 2,
          "paymentPayload": { "...": "signed ERC-3009 authorization" },
          "paymentRequirements": { "...": "config from Step 2" }
        }
      }
    ]
  }
}

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

{
  "order": {
    "id": "ord_abc123",
    "status": "confirmed",
    "payment": {
      "handler_id": "xyz.fd.prism_payment",
      "status": "settled",
      "transaction": "0xe80c...674b"
    }
  }
}

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

Getting Started

Concepts

Architecture

Integrations

API Reference

Going to Production

AI Tooling

Resources

Prerequisites

Advertise the Handler in Your Profile

Authentication

Payment Flow

Step 1: Discover the Handler

Step 2: Create a Checkout Session

Step 3: Authorize with Your Wallet

Step 4: Complete the Checkout

Commerce Payments

Agent Wallet MCP Server

End-to-End Flow

​Prerequisites

​Advertise the Handler in Your Profile

​Authentication

​Payment Flow

​Step 1: Discover the Handler

​Step 2: Create a Checkout Session

​Step 3: Authorize with Your Wallet

​Step 4: Complete the Checkout

Commerce Payments

Agent Wallet MCP Server

End-to-End Flow

Prerequisites

Advertise the Handler in Your Profile

Authentication

Payment Flow

Step 1: Discover the Handler

Step 2: Create a Checkout Session

Step 3: Authorize with Your Wallet

Step 4: Complete the Checkout