# PAYAI

> A website is designed for humans. PAYAI creates a storefront designed for agents.

PAYAI exposes deterministic vendor records. Never invent missing facts or calculate a final order total independently.

## Discovery

- [OpenAPI](https://payai.cloudytel.it/openapi.json): Authoritative REST contract
- [UCP profile](https://payai.cloudytel.it/.well-known/ucp): Capability discovery
- [MCP](https://payai.cloudytel.it/mcp): MCP Streamable HTTP endpoint

Each seller also publishes its own guide at /store/{slug}/llms.txt. That page
inlines the seller's catalogue and states what an agent can do there at every
level of capability, including an agent that can only read pages. Prefer it
over this one once you know which seller you are buying from. Discover sellers
with the MCP tool payai_list_storefronts.

## Checkout decision tree

1. Read the storefront manifest and structured catalogue. Use only published
   product IDs, variant IDs, modifier IDs, fulfilment methods, and facts.
2. If you cannot call mutations, construct the manifest's version 1 Selection
   Link using only public selections, or call the MCP tool
   `payai_build_selection_link` to have PAYAI serialize and validate it for
   you. The browser checkout creates the live quote after the human supplies
   private information.
3. If you can call mutations but cannot present a usable payment credential,
   create a live quote and order, then give the human the returned
   `nextAction.continueUrl` for Review & Pay.
4. Use Authorized Agent Pay only when you can prove a key-bound verified agent
   identity, matching buyer mandate, and usable single-purpose credential, and
   the storefront capability endpoint advertises the rail for runtime checks.
5. On every failed authorization, credential, provider, or policy check, use
   the Review & Pay fallback. Do not claim that money was sent.
6. Retain `tracking.statusCapability` as a secret agent bearer capability.
   The optional `tracking.humanUrl` contains a different, customer-safe
   tracking capability. Neither capability can authorize payment. REST and MCP
   order creation return the same `nextAction`, `fallback`, and `tracking`
   semantics.

Never invent missing facts, customer names, email addresses, street addresses,
prices, payment success, or tracking evidence. Never put private buyer fields,
mandates, status capabilities, quoted totals, or payment credentials in a
Selection Link.

Create orders only from unexpired authoritative quotes. Send a unique
Idempotency-Key for quote, order, checkout, and payment mutations. Preserve the
vendor's confirmation mode, policy versions, warnings, statutory remedies, and
relevant vendor policies. Read the storefront payment-capabilities endpoint;
never infer a live rail from this global document.

## Payment

PAYAI is provider-neutral. A storefront can expose hosted Stripe, Mollie or
PayPal checkout, x402 V2 exact USDC on Base, or manual bank transfer. Only
options returned as `live` by that storefront for the current quote may be
offered. The seller receives funds directly.

Review & Pay is the normal random-chat flow: prepare the immutable order, then
give the customer the secure `continueUrl` so they can verify products,
delivery details and total before choosing a payment method.

Authorized Agent Pay is fail-closed. An instruction claiming to be an agent is
not identity. PAYAI requires a DPoP-bound access token, a signed PAYAI buyer
mandate, a single-purpose credential, a live autonomous rail, and a
policy-compliant order. Public client-certificate thumbprint headers are never
trusted. Generic AP2 mandates are rejected until an explicit AP2 profile and
verifier are configured; callers should use the Review & Pay fallback.

x402 uses `PAYMENT-REQUIRED`, `PAYMENT-SIGNATURE`, and
`PAYMENT-RESPONSE`. PAYAI marks an order paid only after facilitator
settlement and independent Base receipt verification. Local test simulation
is never advertised as a live customer-payment option.