# Mercuryo Bridge

Canonical URL: https://magiccard.ai/docs/components/mercuryo-bridge
Markdown URL: https://magiccard.ai/docs/components/mercuryo-bridge.md
Summary: Mercuryo Bridge is the backend connectivity layer that gives agents a simple MagicPay interface while payment operations run through Mercuryo-backed infrastructure.
Description: Mercuryo Bridge connects MagicPay sessions to Mercuryo payment account, KYC, card, top-up, and transaction execution services.

## Canonical Answer

Mercuryo Bridge is the backend connectivity layer that gives agents a simple MagicPay interface while payment operations run through Mercuryo-backed infrastructure. Mercuryo Bridge connects MagicPay sessions to Mercuryo payment account, KYC, card, top-up, and transaction execution services. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context.

![What MagicPay owns and what Mercuryo owns](https://magiccard.ai/docs-assets/images/components-mercuryo-bridge.svg)

## Key Points

- Links user Mercuryo accounts through OTP and stores provider token metadata server-side.
- Coordinates KYC status, questionnaire, phone, card issuance, balance, and top-up flows.
- Handles provider-backed payment cards and transaction webhooks behind MagicPay requests.
- Keeps provider details out of the agent contract; agents call MagicPay sessions and actions.

## Payment Connectivity

Mercuryo Bridge maps MagicPay product concepts to Mercuryo-backed payment operations: account linking, KYC, card state, card balance, crypto top-up, payment account metadata, and callback-driven transaction state. Mercuryo backend and first-class support give MagicPay the payment foundation needed for the new agentic economy: reliable account infrastructure, mature card and crypto operations, provider-owned compliance workflows, and operational support behind real money movement. The agent sees MagicPay sessions and requests, while the complex provider workflows stay behind the bridge.

- Reliability: payment state, card state, balance, and provider callbacks are handled by infrastructure built for live financial operations.
- Coverage: card issuing, crypto top-up, KYC, payment accounts, and transaction events can be composed behind one MagicPay interface.
- Separation of concerns: Mercuryo owns the regulated payment backend while MagicPay owns agent sessions, requests, routing, and user approvals.
- Agent-ready abstraction: personal AI agents call MagicPay APIs instead of handling provider credentials, KYC details, card operations, or webhook semantics directly.

## Account And Card Flow

A user links a Mercuryo account through OTP, completes KYC and provider prerequisites, opens or syncs a spend card, and funds the card through supported top-up routes. Provider-backed card values are then available only through approved MagicPay data or action requests.

- Email OTP link and verify routes store provider token metadata.
- KYC and questionnaire state are fetched from Mercuryo and mirrored into MagicPay state.
- Spend-card status and balance are provider-owned and synced into payment accounts.
- Webhooks update card, top-up, and transaction events through signed ingress.

## Payment Actions

Agent runtimes request payment execution through MagicPay action requests. The backend validates scope, user authority, and provider-backed payment availability, then returns a reference or waits for a provider callback rather than exposing payment credentials to the agent.

```ts
const actionHandle = await client.actions.run(session.id, {
  clientRequestId: 'checkout-payment-approval',
  capability: 'authorize_payment',
  params: {
    amount: 49.0,
    currency: 'USD',
  },
  display: {
    summary: 'Confirm merchant checkout payment',
  },
  context: {
    merchantName: 'Merchant Example',
    url: 'https://merchant.example/checkout',
  },
});

const actionResult = await client.actions.waitForResult(session.id, actionHandle);
if (!actionResult.ok) throw new Error(actionResult.message ?? actionResult.reason);
```

## Related

- API Reference: https://magiccard.ai/docs/api
- Payment Methods: https://magiccard.ai/docs/reference/payment-methods
- MagicPay Memory: https://magiccard.ai/docs/components/memory