Requirements

To integrate the headless ramp, you will need:

A partner account and API credentials
A frontend (web or mobile) app
If you’re using the SDK, ensure it’s installed
A server for sending requests to MoonPay and receiving webhooks

MoonPay will work with you directly to set up your account and credentials.

Integrating on the web

Content Security Policy

If you embed MoonPay frames on the web, your Content Security Policy (CSP) must allow MoonPay’s iframes and network calls. Your CSP should include at least the following rules:

Content-Security-Policy: frame-src https://*.moonpay.com/; connect-src https://*.moonpay.com/;

Frame permissions

The payment frames (Google Pay and Apple Pay) require the browser payment permission policy. The MoonPay web SDK sets this on the frame it renders, so you do not configure it yourself. If you embed a frame manually, add allow="payment" to the iframe. See the Google Pay and Apple Pay frame references for details. You remain responsible for granting the payment permission on any iframe or WebView of your own that the frame is nested inside.

Configuration

Domain settings

When integrating MoonPay on the web, provide your app’s origin per environment. This allows MoonPay to embed frames securely.

Apple Pay

To use Apple Pay on the web, you must complete Apple’s domain verification to prove ownership of your site. This is currently a manual process.

Integrating in mobile apps

WebViews

This integration supports using WKWebView on iOS and WebView on Android. When using WKWebview on iOS you will need to set allowsInlineMediaPlayback to true for the Connect frame.

Google Pay in a WebView

Google Pay has additional requirements inside mobile WebViews: extra setup on Android, and it is not available on iOS.

Android WebView

Google Pay relies on the Payment Request API, which is disabled by default in Android WebView, so embedding this frame natively requires extra setup.

Requires Google Play services 25.18.30+ and Android WebView for Chrome 137+. The isReadyToPay API returns false when these requirements are not met. See Using Android WebView for full details.

Add the AndroidX WebKit dependency

// build.gradle.kts (app level)
dependencies {
    implementation("androidx.webkit:webkit:1.14.0")
}

Declare the Google Pay intent queries

Declare the required intent queries in AndroidManifest.xml:

<queries>
  <intent>
    <action android:name="org.chromium.intent.action.PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.IS_READY_TO_PAY" />
  </intent>
  <intent>
    <action android:name="org.chromium.intent.action.UPDATE_PAYMENT_DETAILS" />
  </intent>
</queries>

Enable the Payment Request API

Enable the Payment Request API on the WebView, after settings.javaScriptEnabled = true:

import androidx.webkit.WebSettingsCompat
import androidx.webkit.WebViewFeature

if (WebViewFeature.isFeatureSupported(WebViewFeature.PAYMENT_REQUEST)) {
    WebSettingsCompat.setPaymentRequestEnabled(webView.settings, true)
}

Get your app approved for Google Pay

In a WebView, the Google Pay request is issued as a native Android intent from your app, so Google Pay validates your app’s identity, not only MoonPay’s registered domain. The request carries MoonPay’s merchant ID, so your app must be approved under MoonPay’s Google Pay merchant profile. You cannot register it under your own profile: Google Pay ties approval to the merchant ID in the request, so a request carrying MoonPay’s merchant ID from an app registered elsewhere is rejected with OR_BIBED_11.MoonPay registers your app under its profile and submits it to Google for review. Send MoonPay:

Your Android package name.
The SHA-256 fingerprint of your Play app signing key. Use the app signing key, not the upload key.
Screenshots of the Google Pay button and payment flow running in your WebView. Capture these in test mode, which does not require production approval.
A contact for Google’s review questions.

Google reviews each package individually. Until your app is approved, the button loads but the payment request is rejected with OR_BIBED_11, even though the same integration works in Chrome. There, the browser is the registered caller, so Google Pay only checks MoonPay’s domain.Tell MoonPay before you rotate your signing key or ship a new package variant, so the new fingerprint is registered before it reaches production.

Handle custom user agents and nested iframes

Two more embedding details affect whether the request reaches Google Pay:

Custom user agent - if you override the WebView’s user agent string, append GOOGLE_PAY_SUPPORTED so Google Pay recognizes the environment.
Nested iframes - the payment permission must be granted at every level. If the frame is nested inside additional iframes, add allow="payment" to each one.

For a complete native walkthrough that covers rendering the frame and wiring events, see Android manual integration.

Troubleshooting

Error	Meaning	Fix
`OR_BIBED_11`	The embedding app is not approved under MoonPay’s Google Pay profile.	Send MoonPay your app details for approval.
`OR_BIBED_15`	The WebView does not have the Payment Request API enabled.	Enable the Payment Request API on the WebView, as shown above.

iOS WKWebView

Google Pay is not available inside an iOS WKWebView. On iOS, do not render the Google Pay frame. Offer another payment method instead.

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Integrating on the web

Content Security Policy

Frame permissions

Configuration

Domain settings

Apple Pay

Integrating in mobile apps

WebViews

Google Pay in a WebView

Android WebView

Troubleshooting

iOS WKWebView

​Integrating on the web

​Content Security Policy

​Frame permissions

​Configuration

​Domain settings

​Apple Pay

​Integrating in mobile apps

​WebViews

​Google Pay in a WebView

​Android WebView

​Troubleshooting

​iOS WKWebView

Integrating on the web

Content Security Policy

Frame permissions

Configuration

Domain settings

Apple Pay

Integrating in mobile apps

WebViews

Google Pay in a WebView

Android WebView

Troubleshooting

iOS WKWebView