Integration
You can integrate it wherever you’d like. We surface an SDK, and you can pass a variety of query parameters to the widget that is spun up, such as the token you want users to buy and the destination wallet address. See the full list of on-ramp parameters and off-ramp parameters.
What does the customer journey look like?
This depends on the query parameters you use.
What do the different team permissions in the dashboard do?
The Partner Dashboard uses role-based access control to manage team member permissions. Each team member is assigned one of the following roles:
| Role | Access Level | Permissions |
|---|
| Administrator | Full access | Complete access to all dashboard features including dashboard analytics, transactions (with CSV export), team management, developer settings, and account settings. |
| Developer | Limited access | Can view dashboard analytics, transactions, and team members. Can manage API keys and developer settings. Cannot access account settings. |
| Analyst | Read & export | Can view dashboard analytics, transactions (with CSV export), and team members. Cannot access developer settings or account settings. |
| Support Specialist | Transactions only | Limited to viewing and managing transactions. Cannot access dashboard analytics, team management, developer settings, or account settings. |
Does the end user need to provide a wallet, or does MoonPay provide one?
Both are possible. You can pass one, we can let the user create one (BTC and ETH), or you can let users input their own wallet address.
Are there recommended best practices for integrating?
Yes. Best practices for each product are outlined on their respective documentation pages.
Can you customize the automated emails users receive?
We can add a partner logo to the automated email and change the partner name (Partner_Name via MoonPay) in the email subject on request. Reach out to your MoonPay representative.
Errors and troubleshooting
Include a screenshot and steps to reproduce the error when you reach out to your MoonPay representative.
How do I change my API keys?
Go to the Developers > API Keys page of your MoonPay dashboard and hit the roll button next to the API key you wish to replace. You will be given the option to immediately delete the old key or set a 12-hour rollover before the old API key expires.
If you see a CSP error that says buy.moonpay.com refused to connect (or sell.moonpay.com refused to connect for off-ramp), you’ll need to allowlist your production domain(s). We require this when you embed the MoonPay widget in an iframe or use the overlay, drawer, or embedded options, to prevent unauthorized third-parties from embedding the MoonPay widget.
To resolve the issue, add your production domain(s) to the Settings page of your MoonPay dashboard.
If you see a widget error that geo-blocks certain users, confirm that the user is in a region supported by MoonPay. See the non-supported countries, states, and territories for on-ramp and the cryptocurrencies available to sell for off-ramp.
Multiple accounts in production
In our production environment, we only allow one account per user. Creating multiple accounts in production may cause your account to be flagged or blocked.
Test credit cards and KYC info in production
Only genuine card and KYC information may be used in our production environment. Do not use test credit card or test KYC information in production, as this will result in your account being blocked.
MoonPay does not offer an SDK for Flutter. You’ll have to manually embed our widget in a WebView. Consider the following tips:
- You can create your own HTML that uses our Web SDK to embed our Widget. This will allow you to receive our Widget’s events, if you wish. You’ll then need to send them out to your Flutter app layer.
- If you’re experiencing camera issues in Flutter’s WebView, consider using the Flutter plugin compatible with our Web SDK, available at https://pub.dev/packages/flutter_inappwebview.
- You can find further guidance on configuring Flutter camera permissions and other related documentation at https://inappwebview.dev/docs/5.x.x/web-rtc/.
- Custom Origin via
baseUrl Property: For specific requirements, you can set a custom origin using the baseUrl property. This serves as the base URL for any relative paths in the HTML and sets the document’s origin. Example:
InAppWebView(
initialData: InAppWebViewInitialData(
data: htmlContent,
baseUrl: Uri.parse("https://your.custom.origin"),
),
// ... other configurations ...
)
https://app_name, capacitor:// or equivalent as your custom origin for the baseUrl property. From here, add the domain to your allowlist in the settings page of your MoonPay dashboard.
-
Scrolling Issues within the MoonPay widget: When using these overflowing containers in Flutter with a WebViewWidget, you have to specify gesture recognizers: Example:
gestureRecognizers: <Factory<OneSequenceGestureRecognizer>>{
Factory<OneSequenceGestureRecognizer>(
() => EagerGestureRecognizer(),
),
},
-
Avoid using
enableDrag: true when embedding a WebView inside a showModalBottomSheet(), as it may interfere with touch interactions. Instead, provide a dedicated close button for a better user experience.
KYC and app requirements
When not using a MoonPay SDK, make sure that the following requirements are
met so that users can successfully complete KYC (Know Your Customer) steps.
General app requirements for all implementations
All partner apps should ensure the following:
Feature-Policy header for your webpage / frame or any other container has no restrictions for initializing camera like value camera 'none'.Permissions-Policy header doesn’t restrict access to a camera and microphone (for some cases) and if allow is set check for "camera; microphone" values.- When using iOS WKWebview you may need to set
allowsInlineMediaPlayback to true in the WKWebViewConfiguration used in your app. This adjustment ensures that media content, like a camera feed, can be displayed properly within the web view, rather than forcing full-screen playback.
- Your website is being run on a secure
https connection.
WebView requirements
Partner apps that use WebView should ensure the following:
- The web view is able to access device local storage and initialize camera (for older iOS versions, the camera can be accessed only from Safari browser or WebView with
SFSafariViewController)
- HTML5 video playback is allowed (
<video> tags are being used to send instructions): if video-instructions are not played, try using WebChromeClient to enable video playback
- Autoplay in fullscreen mode is disabled and
allowsInlineMediaPlayback is set as true for WebView
- The selector file is implemented on your side (required for KYC document uploads)
Iframe requirements
Partner apps that use iframe should ensure the following:
- Parent page header has no restrictions for initializing the camera, e.g.
camera=()
- Parent page can alternatively include
camera=* in the Permissions-Policy header
- The iframe allow property has
allow="accelerometer; autoplay; camera; encrypted-media; gyroscope; payment"
Payments and payouts
I’m having trouble adding my credit/debit card to my account
Double check you are not in our sandbox environment. Genuine cards should never be added to sandbox accounts.
Has your card already been added to another account? There is a limit of one card per account. Either use the other account or try using another card.
How do you handle chargebacks?
At MoonPay, we treat chargebacks seriously and have processes in place to prevent and handle chargebacks. For more information reach out to your MoonPay account representative.
What payment methods are available by country?
Payment methods offered will vary based on the user’s location. Reach out to your MoonPay account representative for additional details.
How do I get paid?
Details can be found on our partner support site.
Which fiat currencies can users off-ramp with?
We enable payouts in the following fiat currencies:
- USD (United States Dollar)
- GBP (British Pound Sterling)
- EUR (Euro)
Limits
What are my purchase limits?
Purchase limits will vary by region, currency, and level of Know Your Customer (KYC) documents provided. See more on the verifications and limits support page.
Can I adjust purchase limits for my users?
It is not possible to increase or decrease purchase limits for users or partners. MoonPay cannot modify the minimum or maximum purchase amounts for any cryptocurrency.
What are my sell limits?
Sell limits will vary by region, currency, and level of Know Your Customer (KYC) documents provided. See more on the verifications and limits support page.
Supported assets and regions
What cryptocurrencies does MoonPay support?
There are more limitations for US users than non-US users. See the full lists of supported assets for buy / on-ramp and sell / off-ramp.
Do you support Bitcoin Segwit, Taproot and legacy BTC addresses?
Yes, we support Taproot, Segwit, and legacy addresses. A user can send to a BTC wallet address as long as it’s a match for the regex we use to validate: ^[13][a-km-zA-HJ-NP-Z1-9]{25,34}$|^(bc1)[0-9A-Za-z]{39,59}$
Be aware that MoonPay’s Wallet does not support Taproot, and it is advised not to use it for Ordinals to avoid potential loss. This caution specifically applies to MoonPay wallets.
Supported countries
Buy is available for all residents except those in the following countries and US states.
Sell is unavailable for residents of Louisiana, Texas, New York and US Virgin Islands.
Supported payment methods
See the list of MoonPay supported payment methods for US and non-US regions.
Off-ramp specifics
How long does the user have to send their crypto deposit?
The user has 48 hours from when a sell transaction is created to send their crypto to the MoonPay deposit address. If MoonPay does not receive the deposit within 48 hours, the transaction fails with the failure reason Deposit timeout. Your app receives this in the sell transaction webhook payload.
How many block confirmations does MoonPay require before processing/confirming receipt of my crypto?
| code | confirmationsRequired |
|---|
| avax_cchain | 2 |
| axs | 12 |
| bch | 1 |
| bnb_bsc | 14 |
| btc | 1 |
| busd_bsc | 15 |
| eth | 12 |
| eth_arbitrum | 5 |
| eth_immutable | 1 |
| eth_polygon | 12 |
| ltc | 6 |
| sol | 1 |
| trx | 12 |
| usdc | 11 |
| usdc_polygon | 12 |
| usdt | 12 |
| usdt_trx | 12 |
| xlm | 1 |
When are funds refunded to the refund wallet address vs. being returned to the sender’s address?
If MoonPay receives the user’s cryptocurrency and the deposit is valid (correct amount, token, and network), but the sell transaction later fails due to an issue on MoonPay’s side, the funds will be returned to the refundWalletAddress passed in the widget, as long as it’s safe to do so.
However, if the deposit is invalid due to user error such as wrong token, network, or amount, or if the user cancels the transaction before the deposit is confirmed, the funds will automatically be returned to the sender’s address.
Fees
Are there any integration fees to partner with MoonPay?
No, MoonPay does not charge any integration fees.
Are there any trading fees, Payment Service Provider (PSP) fees etc for our clients?
MoonPay doesn’t charge distinct trading or PSP fees. Instead, a variable fee is applied for every transaction.
Any other fees that we need to know?
Based on the specific blockchain, a network or gas fee might be applicable, which varies with network traffic.
Network and API
What are MoonPay’s external IP addresses?
IPv4
- 34.76.118.184
- 34.77.238.249
- 34.79.17.44
- 34.89.242.107
- 34.140.248.51
- 34.159.58.44
- 34.159.89.69
- 35.246.202.26
IPv6 Deprecation: IPv6 support for outbound requests will end on July 15,
2026. Make sure our IPv4 ranges are explicitly allowlisted.
- 2600:1900:4010:bd99::/64
- 2600:1900:40d0:3d::/64
What are the rate limits for the MoonPay REST API?
350 requests in 10 seconds on:
- GET
v3/currency/:code/price
- GET
v3/currency/:code/ask_price
- GET
v3/currency/:code/bid_price
- GET
v3/currency/price
- GET
v3/currency/ask_price
- GET
v3/currency/bid_price
- GET
v3/currency/:code/quote
- GET
v3/currency/:code/buy_quote
- GET
v3/currency/:code/sell_quote
- GET
v3/currency/:code/buy_quotes
- GET
v4/ip_address
30 requests per second on all other endpoints.
Reach out to your MoonPay representative if you require higher limits.
Testing and mobile payments
Which currencies does the sandbox support?
Our sandbox environment supports a limited selection of testnet currencies; test primarily with Ethereum on Sepolia, Solana Testnet, TON or the Bitcoin Testnet. For the full setup, see the sandbox testing guide.
Does MoonPay support Apple Pay and Google Pay?
Yes. See the mobile payments guide for setup and supported scenarios.
