Skip to main content
Learn how to enable Gateway in the MoonPay Gateway overview. MoonPay enables Gateway per account, so contact your account team.
If you haven’t already, sign up for your MoonPay partner account and complete the KYB (Know Your Business) requirements. Once completed, sandbox and production API keys will available in the partner dashboard.

​
MoonPay widget integration

Load the MoonPay widget URL within your in-app webview or browser for web apps. This is used by partners like Moonshot, Jupiter, and Uniswap.
  • Testing (Sandbox): The sandbox environment doesn’t support Gateway, so you’ll need to test in production. If you need to use the sandbox environment, you can test with alternative testnets e.g. ETH Sepolia or SOL.
    https://buy.moonpay.com/?apiKey=pk_test_INSERT_TEST_API_KEY
  • Production: https://buy.moonpay.com/?apiKey=pk_live_INSERT_PRODUCTION_API_KEY

​
Widget parameters

​
Example URL

Below is an example widget URL that uses the parameters above:

​
Widget UX customizations

Go to the Dashboard → Theme settings to set widget colors (button, background, initial loading screen). Match your brand so the widget feels native and improves conversions.

​
Optional API usage

Use our APIs to provide individual asset details and a list of assets available for purchase before directing users to the widget. This allows for a smooth transition between your app and the widget. You can use the following endpoints:
  1. GET /v1/defi/token: Retrieve token details for a specific contractAddress and networkCode.
  2. GET /v1/defi/tokens: Search and retrieve a paginated list of defi tokens.
These endpoints belong to the widget API at https://api.moonpay.com and use your API key. They’re separate from the Platform API’s List assets endpoint.

​
Troubleshooting

  • Webview KYC requirements: If loading the MoonPay widget within a mobile application webview, follow these configurations to make sure the KYC and user camera will function correctly. See requirements.
  • Third-party cookies / iframe blockers: Some browsers/extensions block widget flows. Test in a clean profile or incognito mode with extensions disabled. Apple Pay will not work within iframes.
  • Invalid or missing params: Make sure apiKey, contractAddress, a supported networkCode, and a valid walletAddress and signature are all present.
  • Ad blockers / privacy settings: Ad blockers and privacy settings can break widget scripts.
  • CORS / Referrer policies: If embedding the widget in an iframe, add the parent domain(s) to the allowlist in the partner dashboard.
  • Rate limits / throttling: Avoid rapid programmatic opens; all opens must be user-initiated.
  • Wallet infrastructureIf you need help setting up wallet infrastructure, MoonGate lets users sign in with Google, Apple, or Ethereum and auto-creates a wallet. Reach out to your MoonPay representative for more details.