Fiat-to-crypto onramp and offramp widget with global card, bank, and Apple/Google Pay support. Web, React, and React Native SDKs plus a Node SDK for signed URLs and webhooks.
- 01fiat onramp
- 02fiat offramp / cash-out
- 03global card and bank coverage
- 04drop-in widget
- 05regulated KYC handoff
- pnpm add @moonpay/moonpay-react
- pnpm add @moonpay/moonpay-node
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_MOONPAY_PUBLISHABLE_KEY | Client | MoonPay publishable key (`pk_test_...` for sandbox, `pk_live_...` for production). Determines the SDK environment automatically. |
| MOONPAY_SECRET_KEY | Server | Secret key used server-side to sign widget URLs and verify webhook signatures. |
Use MoonPay for fiat onramp/offramp. Wrap the app in `<MoonPayProvider apiKey={process.env.NEXT_PUBLIC_MOONPAY_PUBLISHABLE_KEY} debug={isDev}>` then mount `<MoonPayBuyWidget>` or `<MoonPaySellWidget>` with a `walletAddress` and a destination `currencyCode`. For production-grade flows, generate a signed URL server-side with `@moonpay/moonpay-node` (`MoonPay.url.generateSignature`) so parameters cannot be tampered with. Verify webhook events from MoonPay using the `Moonpay-Signature` header before crediting users.
- ⚑MoonPay handles KYC/AML on their side — your app loses the user during verification. Persist a session ID and listen to webhook events to know when funds settle; do not assume widget close = success.
- ⚑Sandbox (`pk_test_...`) only mints test crypto on testnets and won't trigger real transfers — make sure the widget environment matches the wallet network you're funding.
- ⚑Unsigned URLs let users tweak the destination wallet in the URL — always sign the widget URL server-side for any non-trivial app.
- ⚑Geographic and asset availability differs widely (e.g., USD off-ramp for US states, EU IBAN, etc.); call the `/v3/currencies` API at runtime rather than hard-coding the supported list.
- ⚑Offramp requires the user to send crypto to a MoonPay-provided deposit address — your UX must surface that address clearly and handle expiry.