Mercuryo Bridge
Mercuryo Bridge is the backend connectivity layer that gives agents a simple MagicPay interface while payment operations run through Mercuryo-backed infrastructure.
- 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.
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);