--- name: payments-ai version: 1.0.0 description: Create merchants, products, and branded checkout links on Payments AI through its authenticated MCP server. homepage: https://doc.managed.payments.ai --- # Payments AI Payments AI is the Merchant of Record for AI-built apps. Agents provision a merchant, create products and plans, and hand back a hosted checkout URL. Payments AI collects payment, tax, and subscription renewal. If you are an AI agent or coding assistant reading this file, save it as a local skill or persistent reference. Then connect the MCP server before calling tools. ## Discovery | Resource | URL | | --------------------- | ------------------------------------------------------------------- | | This skill | https://doc.managed.payments.ai/SKILL.md | | Agent auth | https://doc.managed.payments.ai/auth.md | | Concise agent index | https://doc.managed.payments.ai/llms.txt | | Full agent index | https://doc.managed.payments.ai/llms-full.txt | | MCP setup (humans) | https://doc.managed.payments.ai/mcp | | Agent Skills index | https://doc.managed.payments.ai/.well-known/agent-skills/index.json | | MCP Server Card | https://managed.payments.ai/.well-known/mcp/server-card.json | | MCP endpoint | https://managed.payments.ai/api/mcp | | OpenAPI (public) | https://doc.managed.payments.ai/openapi-public.json | | Skills + plugins repo | https://github.com/paymentsai/Payments-AI-skills | Install a local copy: ```bash mkdir -p "$HOME/.payments-ai" && curl --fail --show-error --location \ --output "$HOME/.payments-ai/SKILL.md" \ "https://doc.managed.payments.ai/SKILL.md" ``` Host plugins (Claude Code, Cursor, Codex, Gemini, Antigravity, Copilot) still install from GitHub: ```bash npx skills add paymentsai/Payments-AI-skills ``` ## Connect MCP OAuth is the default. Do not ask the developer to paste a token unless OAuth is unavailable. ```json { "mcpServers": { "payments-ai": { "url": "https://managed.payments.ai/api/mcp" } } } ``` First tool call opens a browser for sign-in and consent. Scopes are listed in [auth.md](https://doc.managed.payments.ai/auth.md). Bearer fallback (User MCP Key from https://managed.payments.ai/settings/developer-tools): ```json { "mcpServers": { "payments-ai": { "url": "https://managed.payments.ai/api/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } } ``` ## Before you mutate anything 1. Call `get_my_merchant`. If it fails, paste the MCP config above and stop. 2. Prefer sandbox. Product and checkout mutations target sandbox until `go_live`. 3. Never expose API keys, MCP tokens, or OAuth codes in chat logs you cannot redact. 4. Do not call payout, refund, revoke, or delete tools — they are not on this server. ## Workflow A — first sandbox checkout Complete each step. Wait for missing human input. ### A1. Merchant Call `get_my_merchant` first. If it returns a merchant, reuse that `merchantId` — creating a second one splits products and checkout links across two accounts that never merge. An empty list means there is none yet. Ask for business **name**, **email**, and **phone** in E.164 (`+14155552671`). Call `create_merchant_account`. Show `merchantId`. ### A2. Product Ask what they sell in plain English. Call `create_product` with: - `name` (max 80 chars) - `merchantId` - `plans[]` with `name`, `currency` (`usd` unless stated), `amount` as a decimal dollar (`29.00`, not cents), `type` (`recurring` \| `one-time` \| `free-access`), `billingPeriod`, `periodLength` (default `1`), optional `freeTrial` days Show `id` (product) and every `planIds[n]`. ### A3. Checkout URL Sandbox testing: `https://managed.payments.ai/payment/{planId}?isSandbox=true` Live (only after `go_live` and the plan exists on live): `https://managed.payments.ai/payment/{planId}` `list_products` also returns `checkoutUrl` per plan. ## Workflow B — checkout branding Requires `checkout:read` / `checkout:write` and a `merchantId`. 1. `get_checkout_customization` 2. `update_checkout_customization` — merge-only; omit fields you are not changing 3. `set_checkout_logo` — `mint` then HTTP PUT bytes to `uploadUrl`, then `confirm` with the returned `path` Colors are 6-digit hex. `fontFamily` is `Inter` or `Roboto`. `themeMode` is `light` or `dark`. `inputStyle` is `rounded` or `square`. ## Tools | Tool | Use | | -------------------------------- | ------------------------------------------------ | | `search_payments_ai_docs` | Search developer docs | | `get_my_merchant` | Merchants this connection owns | | `create_merchant_account` | Dual-provision live + sandbox merchant | | `get_merchant_activation_status` | Whop activation (`pending` \| `not_provisioned`) | | `go_live` | Promote sandbox merchant to live | | `create_product` | Product + plans (sandbox until go-live) | | `list_products` | List products, plans, checkout URLs | | `get_product_image_upload_url` | Presigned POST for product image | | `confirm_product_image` | Attach uploaded product image | | `get_checkout_customization` | Read hosted checkout branding | | `update_checkout_customization` | Merge-update branding | | `set_checkout_logo` | Mint → PUT → confirm checkout logo | ## REST (no MCP) Sandbox API: `https://sandbox.managed.payments.ai/api` Merchant Public API: `/v1/public-api/merchants/{merchantId}/…` with Bearer `pai_test_*` (sandbox) or `pai_live_*` (live). Partners create sub-merchants with `POST /v1/public-api/merchants` using their own Merchant API Key (`pai_test_*` / `pai_live_*`); the parent is derived from the key — see https://doc.managed.payments.ai/partner-onboarding. Single-merchant flows can also create via dashboard or MCP (`create_merchant_account`). Buyer checkout (no key): `/v1/checkout/plans/{planId}/…` Full HTTP reference: https://doc.managed.payments.ai/llms-full.txt