API Documentation

All API requests require authentication. MagnetPay supports two authentication methods: API key pair (for server-to-server) and Bearer token (for dashboard sessions). Include your credentials in every request header. Keys are scoped per environment (sandbox / production).

Accept payments via cards, bank transfers, UPI, and 30+ local methods. MagnetPay automatically routes to the optimal provider based on currency, region, and cost.

Manage recurring billing with flexible intervals, trial periods, metered usage, and automatic retry logic. Supports proration and mid-cycle plan changes.

Create shareable payment links with no code required. Perfect for invoicing, one-time charges, and donation pages. Links can expire and support quantity limits.

Create professional invoices with line items, tax calculations, and automated reminders. Invoices can be paid via hosted payment page or marked as paid manually.

Accept and send crypto across 8 blockchain networks. HD wallet derivation per customer. Automatic deposit detection with configurable confirmation thresholds.

Issue virtual and physical cards across multiple providers through a unified API. Manage card lifecycle, set spending controls, and fund cards instantly.

Manage customer profiles for payments, subscriptions, and cards. Customers store payment methods, addresses, and billing preferences.

Create discount coupons for payments and subscriptions. Supports percentage and fixed-amount discounts with optional usage limits and expiration dates.

Report metered usage for usage-based billing subscriptions. Usage is aggregated per billing period and charged on the next invoice.

Create hosted checkout sessions for a fully managed payment page. Customers are redirected to MagnetPay's secure checkout, then back to your site on completion. No frontend integration needed.

Check your merchant account balances in real time. Balances are broken down by currency with available, pending, and reserved amounts. Use this to track funds before requesting payouts.

Request payouts to withdraw funds from your MagnetPay balance to your bank account or crypto wallet. Payouts are processed in batches and typically settle within 1-3 business days for bank transfers.

Check the real-time status of any payment or payout. Use these endpoints to poll for status updates, verify payment completion, or confirm payout delivery. For real-time updates, we recommend using webhooks instead of polling.

Track settlement batches that aggregate your completed payments. Settlements are processed on your configured schedule (daily, weekly, or custom) and include detailed breakdowns of gross volume, fees, and net amounts.

Virtual IBANs and local bank details in 30+ countries. Receive payments via bank transfer into your MagnetPay balance without a local entity. Funds are automatically converted and settled.

Real-time foreign exchange rates and currency conversion. Get mid-market rates or convert amounts between 50+ currencies with transparent markup. Rates are refreshed every 60 seconds.

Track and manage refunds across all payment methods. Refunds are created via the Payments endpoint and can be tracked independently. Supports partial and full refunds with detailed status tracking.

Unified view of all financial movements across payments, refunds, payouts, card loads, and crypto transfers. Use transactions for reconciliation, reporting, and audit trails.

Save and manage bank accounts for customers and merchants. Bank accounts are used for ACH/SEPA debits, payouts, and recurring bank transfers. All accounts are verified via micro-deposits or instant verification.

Initiate and manage ACH, SEPA, and wire transfers between bank accounts and your MagnetPay balance. Supports both push (send) and pull (debit) transfer types with real-time status tracking.

Identity verification for individuals (KYC) and businesses (KYB). Submit documents, track verification status, and manage beneficial owners. Supports automated verification via Veriff integration.

Accept payments via Apple Pay and Google Pay through a unified API. Create wallet sessions, validate merchants, and complete payments with tokenized card data from the device wallet.

Declare and track merchant deposits into your MagnetPay balance. Get bank details for manual wire transfers and monitor deposit status until funds are credited.

Define products and their pricing for use in checkout sessions, payment links, and subscriptions. Products represent your goods or services, and prices define how much to charge.

Check the health and operational status of the MagnetPay API. Use this endpoint for monitoring, uptime checks, and verifying connectivity before critical operations.

Receive real-time notifications for payment events. All webhooks are signed with HMAC-SHA256 for verification. Failed deliveries are retried with exponential backoff (up to 72 hours).

All API errors follow a consistent format with a machine-readable error code, human-readable message, and HTTP status. Use the error code for programmatic handling and the message for debugging.