# Pay By AI

> A Stripe-powered payments platform that lets AI agents pay merchants on behalf of users. Non-custodial by design — funds route directly from user to merchant via Stripe Connect destination charges. Pay By AI never holds money and never sees card numbers.

## Core concepts

- **Agent session (budget)** — a bearer token a user mints to let an AI spend on their behalf. Carries a spending limit, merchant allowlist, and expiry, all enforced server-side before any payment.
- **Payment request** — an opaque token issued by a merchant. The merchant says "pay this token to complete the order"; the agent pays the token; a webhook closes the loop.
- **Mode** — every account is either `test` or `live`. Data is fully isolated per mode.
- **Non-custodial** — Pay By AI orchestrates; Stripe moves the money. We never hold a balance.

## Authentication

- **Agents** authenticate to the MCP endpoint with `Authorization: Bearer <agent_session_token>`. Tokens start with `pbai_sess_`.
- **Merchants** authenticate to the REST API with `Authorization: Bearer <merchant_api_key>`. Keys are formatted `pbai_mk_<mode>_<48-hex>` — the mode is visible in the prefix.
- **Users** authenticate to the web dashboard via Clerk (Google OAuth, email, optional SMS 2FA).

## MCP endpoint

- URL: `https://www.paybymyai.com/api/mcp`
- Transport: JSON-RPC 2.0 over HTTPS (stateless)
- Protocol version: `2025-03-26`
- Tools:
  - `get_merchant(id)` — look up a merchant by ID
  - `search_merchants(q?, limit?)` — search merchants by name
  - `get_payment_request(token)` — preview a token before paying
  - `pay_payment_request(token, paymentMethodId)` — pay a token; requires an authenticated session
  - `list_payment_methods()` — list the authenticated user's stored cards
  - `get_current_budget()` — show the authenticated session's limit, spent, remaining, allowed stores, and expiry

## REST API (merchants)

Base: `https://www.paybymyai.com/api`

- `POST /merchants/onboarding` — create merchant + Stripe Connect account + return onboarding link and `apiKey`
- `POST /payment_requests` — mint a payment token (auth: merchant key)
- `GET /payment_requests/{token}` — preview a token (no auth; token IS the credential)
- `POST /payment_requests/{token}/pay` — pay a token (called by buyer/agent)
- `POST /payment_requests/{token}/cancel` — cancel a pending token (auth: merchant key)
- `POST /webhooks/stripe/{mode}` — Stripe webhook receiver (configure one endpoint per mode in Stripe dashboard)

## Setup guides

- [Customer setup](https://www.paybymyai.com/docs/customers) — add a card, connect an AI assistant, create a budget with spending limits.
- [Merchant setup](https://www.paybymyai.com/docs/merchants) — onboard via Stripe Connect, mint tokens from your backend, handle webhooks.

## Full API reference

- [API index](https://www.paybymyai.com/docs/api) — hub, with links below.
- [REST reference](https://www.paybymyai.com/docs/api/rest) — every endpoint, auth model, request/response schemas, error codes, curl examples.
- [MCP reference](https://www.paybymyai.com/docs/api/mcp) — transport spec, auth, initialize handshake, and per-tool reference with consent enforcement rules.

## Security guarantees

- Card data never stored by Pay By AI; PCI scope stays with Stripe.
- Every agent session (budget) enforces spending limit + merchant allowlist + expiry before a PaymentIntent is created.
- Any agent session can be revoked instantly by the user in the dashboard.
- Non-custodial: funds flow user → merchant via Stripe; we have no balance to drain.