Integration design guide

Documentation Index

Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt

Use this file to discover all available pages before exploring further.

​

Go-live requirements

• Multiple entry points — Buy buttons in home screen, main app navigation, and individual cryptocurrency screens. See Buy button placement.
• Amount input — Pre-fill fiat/crypto amount using currencyCode with baseCurrencyAmount or quoteCurrencyAmount; show minimum and maximum buy limits. See Amount input screen and Minimum and maximum buy limits.
• Payment method selection screen — Show all supported payment methods, payment method logos, estimated transaction completion times, and default to Apple Pay on iOS. See Payment method selection and Supported payment methods.
• Provider selection screen — Show ID verified badges for returning users, quotes from /buy_quote using paymentMethod, and estimated completion times. See Provider selection.
• Pre-fill the customer’s email address — Pre-fill via the email parameter to skip the widget login screen. See Pre-fill the customer’s email address.
• Pre-fill the customer’s wallet address(es) — Pass walletAddress or walletAddresses (with currencyCode or defaultCurrencyCode when using the singular form), and sign URLs with your secret key. See Pre-fill the customer’s wallet addresses in the widget.
• Transaction tracking — Display a toast after the user completes their transaction with a link to the MoonPay transaction tracker, or to your own history page. See Track the order status.
• Mobile app configuration — Use a fullscreen in-app browser without a nav bar, allow KYC, and allow pop-ups at the browser level. See Mobile integrations.

​

User journey demo

​

Implementation details

​

Buy button placement

• Home screen
• Main app navigation
• Cryptocurrency-specific screens

​

Currency selector

• List all cryptocurrencies available for purchase through your MoonPay integration
• Include a search bar and filters for ease of use
• Show the currency icon, abbreviation, full name, and network of each token so users can easily browse the list. Cryptocurrency and Fiat asset images can be found by accessing our v3/currencies API.

​

Amount input screen

• When opening the MoonPay widget, pass the widget parameterscurrencyCode withbaseCurrencyAmount or quoteCurrencyAmountto pre-fill the fiat or crypto amount.
• Allow users to change which crypto they’re purchasing on this screen without leaving the flow
• Validate minimum and maximum buy amounts against our Limits endpoint

​

Minimum and maximum buy limits

​

Payment method selection

• Show all payment methods supported by MoonPay, depending on the user’s region and currency
  • All available payment methods per transaction type, region, and fiat currency can be surfaced using the /payment_method_config endpoint
• Show payment method details that are returned in the /payment_method_config response
  • Use payment method logos
  • Show estimated transaction completion times
• Default to Apple Pay on iOS, as Apple Pay typically has higher transaction success rates
• Pre-fill the ?paymentMethod widget param with the selected payment method

• Update ?paymentMethod when calling the /buy_quote endpoint and showing the widget
• Add the new payment method as an option in your app, including the logo, estimated transaction completion times
• Any other payment method-specific requirements

​

Provider selection

• ID verified badge for users who have completed KYC
• Quotes from our/buy_quote endpoint using paymentMethod
• Supported payment methods and their logos

​

ID verified and previously used badges

​

Payment method logos

• On-ramp payment methods
• Off-ramp payout methods
• Checkout payment methods

​

Loading screen

• Go to the B2B dashboard
• Navigate to “Theme” → “Loader”
• Choose your preferred loader type (MoonPay default or generic spinner)
• Select custom colors to match your brand
• Save changes

​

Skip the amount screen

• currencyCode
• baseCurrencyCode
• baseCurrencyAmount
• walletAddress
• signature

​

Login options

​

Pre-fill the customer’s email address

​

Pre-fill the customer’s wallet address

• Pass currencyCode or baseCurrencyCode and
• Sign URLs server-side

​

Pre-select the payment method

​

Track the order status

1. Transaction tracking toast message: After a user completes a transaction, show a toast message that persists until the crypto has been received in the user’s wallet. When clicked, either the MoonPay transaction tracker or your app’s transaction history page should open.
   • Partners not able to use webhooks for this toast message should implement a transaction history screen and use API calls to retrieve transaction data on-demand.
   
2. Use the MoonPay transaction tracker: We return the transaction tracker URL in our webhooks and API in the data.returnURL object. Example tracker URL: https://buy.moonpay.com/transaction_receipt?transactionId=45751523-c3e2-47a5-ad0f-e5cb89e94037. You can optionally pass the apiKey parameter to enable your custom theme on the tracker.
   
3. Use your own transaction tracker: You can optionally create your own transaction tracking screen that shows transaction data from our API and webhooks. We recommend that partners use the redirectURL parameter to route users to your destination URL (HTTPS or Universal/App Link) instead of the default MoonPay order status screen. Custom-scheme links (e.g., myapp://…) are not supported. To enable automatic redirection for users, please contact your MoonPay representative.
   
   

​

API and webhook objects for transaction tracking

​

Mobile integrations

​

iOS in-app browser setup

import { WebView } from "react-native-webview";

const YourMoonpayWidgetScreen = ({
  route: {
    params: { moonpayWidgetUrl },
  },
}) => <WebView source={{ uri: moonpayWidgetUrl }} enableApplePay />;

import { createNativeStackNavigator } from "@react-navigation/native-stack";

const Stack = createNativeStackNavigator();

<Stack.Navigator
  component="widgetScreenName" // Your widget screen name
  options={{ presentation: "modal" }}
/>;

​

Android in-app browser setup

import InAppBrowser from "react-native-inappbrowser-reborn";

export const openBrowser = async ({ link }) => {
  try {
    InAppBrowser.close();
    const browserResult = await InAppBrowser.open(link, {
      forceCloseOnRedirection: false,
      showInRecents: true,
      animated: true,
    });

    // Automatically closes the browser if there is an issue with loading the widget.
    if (browserResult?.type === "dismiss") {
      InAppBrowser.close();
    }

    return browserResult;
  } catch (e) {
    // handle error
  }
};

​

App requirements for KYC

​

General app requirements for all implementations

• 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

• 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

• 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"

​

Feature comparison

​

Customize logos and themes

​

Custom logos

• 1 rectangular logo for transactional emails (jpg or png formats)

​

Custom themes

​

Adding Domains to the whitelist