Model Context Protocol endpoint

Look up a merchant by ID.

{
  "id": "string"
}

{
  "id": "string",
  "name": "string",
  "stripeAccountId": "string",
  "mode": "\"test\" | \"live\""
}

Search merchants by name (case-insensitive substring match).

{
  "q": "string (optional)",
  "limit": "number (optional, max 100, default 20)"
}

Merchant[] — ordered newest first.

Browse/keyword-search a merchant's catalog. Pay By AI proxies to the merchant's own commerce MCP (their WooCommerce/Shopify plugin) — agents only need to connect to Pay By AI.

{
  "merchantId": "string (from search_merchants)",
  "q": "string (optional keyword)",
  "limit": "number (optional, 1-50, default 20)",
  "page": "number (optional, 1-based, default 1)"
}

{
  products: [{ id, title, price, currency, availableForSale, imageUrl, ... }],
  page, limit,
  merchantId, merchantName
}

Fetch a single product's full detail (variants, stock) at a merchant. Proxied to the merchant's commerce MCP.

{
  "merchantId": "string",
  "productId": "string | number"
}

{
  id, title, description, type, price, currency,
  stockQuantity, availableForSale,
  variants: [{ id, attributes, price, availableForSale, stockQuantity }],
  imageUrl,
  merchantId, merchantName
}

Create an order at a merchant and mint a Pay By AI payment token — proxied to the merchant's commerce MCP. Agent collects shipping + email from the user and passes them here. Then call pay_payment_request with the returned token.

{
  "merchantId": "string",
  "items": "Array<{ productId, variantId?, quantity }>",
  "email": "string",
  "shippingAddress": "{ firstName, lastName, address1, address2?, city, state, country, postcode, phone? }",
  "note": "string (optional)"
}

{
  token: "pr_... — pass to pay_payment_request",
  amountCents, currency, description,
  merchantId, merchantName
}

The merchant creates the order in a pending state — it's not fulfilled until Pay By AI webhooks the merchant payment_request.paid after the token is paid.

Preview a payment request before paying. The token IS the credential for this tool.

{
  "token": "string"
}

{
  id, merchantId, merchant: { id, name, stripeAccountId },
  amountCents, currency, description, status,
  merchantMetadata, expiresAt, createdAt
}

Pay a payment request with one of the authenticated user's stored payment methods. Consent-bounded.

{
  "token": "string",
  "paymentMethodId": "string (one of the user's stored PMs)"
}

{
  paymentRequestId: "pr_...",
  paymentIntentId: "pi_...",
  status: Stripe PaymentIntent status (usually "succeeded" or "processing")
}

Before dispatching the PaymentIntent we check spending_cap_exceeded and merchant_not_allowed. After success we increment the budget's spent counter. Stripe webhooks handle the eventual settle + merchant notification separately.

List the authenticated user's stored payment methods. Default card is first.

{} — no arguments.

PaymentMethod[] — each with { id, brand, last4, expMonth, expYear, isDefault }

Return this session's own budget — limit, spent, remaining, allowed stores, expiry. Does not reveal the user's other budgets. Use it to answer 'how much can I still spend?' and similar.

{} — no arguments.

{
  limitCents: number | null,        // null = unlimited
  spentCents: number,
  remainingCents: number | null,    // null when limitCents is null
  allowedMerchantIds: string[],     // empty = any merchant
  expiresAt: string | null,         // ISO timestamp or null = no expiry
  createdAt: string                 // ISO timestamp
}

spentCents reflects the session state loaded at the start of this MCP request. If a payment happened during the same request, the new spend is recorded asynchronously and may not appear in the response. For nearly all user queries this is fine; if you need exact post-pay accuracy, call get_current_budget again in a subsequent turn.