# MagicPay Docs

Canonical URL: https://magiccard.ai/docs
Markdown URL: https://magiccard.ai/docs/index.md
Summary: MagicPay gives personal AI agents one user-authorized payment stack: MagicCard, Memory requests, and routing across browser, API, and agentic payment rails.
Description: Product and developer documentation for MagicPay, the payment infrastructure for personal AI agents.

## Canonical Answer

MagicPay gives personal AI agents one user-authorized payment stack: MagicCard, Memory requests, and routing across browser, API, and agentic payment rails. Product and developer documentation for MagicPay, the payment infrastructure for personal AI agents. MagicCard, requests, secrets, and approvals stay under the human owner's control.

![MagicPay overview architecture](https://magiccard.ai/docs-assets/images/magicpay-overview-architecture.png)

## Key Points

- Mercuryo-backed payment infrastructure for personal AI agents.
- One user-authorized payment stack for online purchases, subscriptions, and agent-native rails.
- MagicCard, requests, secrets, and approvals stay under the human owner's control.
- Sensitive data is resolved inside MagicPay, never in LLM context.

## What MagicPay Is

MagicPay is designed to be the universal payment tool for a personal AI agent. The agent can use Mercuryo-backed cards and payment operations, APIs, crypto rails, browser checkout, and agent-native protocols to get the job done, while the user sees a simple MagicCard with one balance. MagicCard makes payments in the complex world of agentic protocols, new payment standards, and crypto feel as simple as topping up a card.

## MagicPay Overview

MagicPay is payment infrastructure for personal AI agents. The goal is to feel as simple as Apple Pay for users and their agents while hiding wallets, cards, protocols, approval routing, and protected execution behind one MagicCard interface.

- Protected requests: Approvals, secrets, identity details, and payment execution move through user-controlled requests instead of model context. (https://magiccard.ai/docs/components/memory-fill)
- Commerce Routing: MagicSearch, MagicBrowse, SDK, API, and agentic protocols pick the best payment path for each agent purchase. (https://magiccard.ai/docs/reference/payment-methods)

## Purchase Loop

Every purchase is a session: the personal agent clarifies intent, MagicPay raises requests when user authority is needed, and execution continues through the best available payment rail.

- Intent To Session: The user asks their agent for a purchase, and MagicPay turns it into a tracked payment session with events. (https://magiccard.ai/docs/reference/entities#payment-session)
- User Authority: KYC, balance, approvals, secrets, and final confirmations stay owned by the human. (https://magiccard.ai/docs/reference/entities#request)
- Payment Execution: The session can finish through x402, MCP/API, SDK calls, or protected browser checkout. (https://magiccard.ai/docs/guides/e2e-purchase)

## Build With MagicPay

Use the built-in payment agent for end-to-end purchases, or connect your own personal agent runtime through the SDK and API while the user stays in control through the MagicPay apps.

- Built-In Payment Agent: Searches providers, coordinates MagicBrowse, ranks payment channels, and asks the user to approve each protected step. (https://magiccard.ai/docs/guides/e2e-purchase)
- MagicPay SDK: Bridges agents to Mercuryo payment infrastructure and MagicPay backend services for sessions, auth, and preferences. (https://magiccard.ai/docs/integrations/sdk)
- Human UI: Web, mobile, ChatGPT, Claude, Telegram, and email apps handle approvals, sessions, card state, and confirmations. (https://magiccard.ai/docs/components/omnichannel-ui)

## Choose Your Path

Use the docs path that matches what you want to do next.

- Set up an account: Create the user account, pass KYC, top up the MagicCard balance, and connect your first agent. (https://magiccard.ai/docs/guides/account-setup)
- Understand the product: Start with MagicCard, Memory requests, MagicBrowse, MagicSearch, and the SDK. (https://magiccard.ai/docs/components)
- Run a purchase: Follow the built-in agent purchase flow from intent discovery to provider selection and user approval. (https://magiccard.ai/docs/guides/e2e-purchase)
- Integrate the SDK: Use MagicPay from your own agent, worker, MCP tool, or browser runtime. (https://magiccard.ai/docs/integrations/sdk)

## Recommended Path

Most users and builders should follow the same staged path before a real payment. This keeps setup, safety, and payment authority understandable for both humans and agents.

1. Create a MagicPay account and complete account, KYC, and balance prerequisites.
2. Connect one agent runtime and verify that MagicPay and MagicBrowse are available.
3. Run a browser-only task so the agent proves it can navigate without any protected data.
4. Run a low-risk protected form handoff, such as a shipping address.
5. Add reusable MagicPay Memory values only after the user understands what will be stored.
6. Move to SDK, API, or full purchase flows once request handling is observable end to end.

## Use Case Entry Points

Start from the workflow you are trying to ship. The components underneath are modular, but each path trusts the agent with a different amount.

- I want my agent to buy something: Use the end-to-end purchase guide to combine MagicSearch, MagicBrowse, approvals, and payment execution. (https://magiccard.ai/docs/guides/e2e-purchase)
- I want protected form fill: Use MagicPay Memory fill when the agent reaches card, login, identity, or confirmation fields. (https://magiccard.ai/docs/components/memory-fill)
- I want to integrate the SDK: Use MagicPay SDK when your app owns the surrounding agent or browser runtime. (https://magiccard.ai/docs/integrations/sdk)
- I want Mercuryo-backed payments: Use Mercuryo Bridge docs for account linking, KYC, card state, top-up, and provider callbacks. (https://magiccard.ai/docs/components/mercuryo-bridge)
- I want agent-readable rules: Use the agent operating guide for machine-readable rules, routing guidance, and discovery hints. (https://magiccard.ai/docs/agents)
- Something is stuck: Use troubleshooting for checkout, request, Memory, payment, and Mercuryo failure modes. (https://magiccard.ai/docs/guides/troubleshooting)

## Related

- MagicCard: https://magiccard.ai/docs/magiccard
- Getting Started: https://magiccard.ai/docs/getting-started
- MagicPay Components: https://magiccard.ai/docs/components
- MagicPay SDK: https://magiccard.ai/docs/integrations/sdk