Overview

The React Native SDK wraps the MoonPay Developer Platform in a <MoonPayProvider> and a useMoonPay() hook. The SDK ships with TypeScript types for autocomplete and inference. The SDK is tested against:

React Native 0.73+
React >=18
react-native-webview 13.0+
iOS 14+ and Android API 26+

Install

Install the SDK package and its peer dependency:

pnpm i @moonpay/platform-sdk-react-native react-native-webview

bun add @moonpay/platform-sdk-react-native react-native-webview

npm i @moonpay/platform-sdk-react-native react-native-webview

Follow the react-native-webview install guide to link the native module. On iOS, run pod install from your ios/ directory. You also need a Web Crypto getRandomValues polyfill, which is a required setup step on React Native. See Register a crypto polyfill below.

Register a crypto polyfill

The SDK requires a Web Crypto getRandomValues polyfill on React Native. The key exchange behind getConnection() calls crypto.getRandomValues, and React Native’s Hermes engine does not implement the Web Crypto API. Register a polyfill before the SDK runs, or the first getConnection() fails with crypto.getRandomValues must be defined.

The SDK does not bundle a polyfill, because the right one depends on whether you run Expo or bare React Native. Import it as the very first line of your app entry, before you import the SDK or mount <MoonPayProvider>. A dedicated polyfills.ts that you import first keeps the ordering explicit.

// polyfills.ts, imported first, before the MoonPay SDK
import * as Crypto from "expo-crypto";

if (typeof globalThis.crypto?.getRandomValues !== "function") {
  globalThis.crypto = {
    ...globalThis.crypto,
    getRandomValues: (array) => Crypto.getRandomValues(array),
  };
}

// index.js, first import, before the app
import "react-native-get-random-values";

On Expo, expo-crypto exposes a Web-Crypto-compatible getRandomValues that works in Expo Go, but it does not install itself on the global. You register it yourself with the snippet above. Import polyfills.ts before anything else. With Expo Router, put the import at the top of your root layout, since the router owns the entry point. On bare React Native, react-native-get-random-values installs the global as a side effect of the import. Keep it as the first import in index.js.

expo-standard-web-crypto offers a polyfillWebCrypto() one-liner as an alternative on Expo. It falls back to an insecure Math.random when the native RNG is unavailable, so prefer the expo-crypto snippet above, which uses the native RNG directly.

Conventions

Provider + hook

Mount <MoonPayProvider> near the top of your app tree and call useMoonPay() from any descendant component to get the client. Pass the sessionToken at mount, or supply it later with initialize(). The SDK presents frames in two ways:

Client methods such as client.connect() or client.setupWidget() open a full-screen modal managed by the provider. Hidden utility frames (connection check, headless buy, reset) render at zero size.
Inline components such as <MoonPayConnect> or <MoonPayWidget> render the frame wherever you place them in your layout.

App.tsx

import { MoonPayProvider } from "@moonpay/platform-sdk-react-native";

export default function App() {
  return (
    <MoonPayProvider sessionToken="c3N0XzAwMQ==">
      <YourApp />
    </MoonPayProvider>
  );
}

`Result<T, E>`

Most SDK functions return a Result<T, E> instead of throwing.

Field	Type	Required	Description
`ok`	`boolean`	✅	Whether the operation succeeded.
`value`	`T`		Present when `ok` is `true`.
`error`	`E`		Present when `ok` is `false`.

Use this pattern to branch on success vs failure:

const result = await client.getConnection();

if (!result.ok) {
  // Handle error
  console.error(result.error);
  return;
}

console.log(result.value);

Function reference

These pages document the provider, hook, and individual SDK functions:

Mount the provider

Access the client with useMoonPay()

Check the customer's connection

Connect a customer

Reset the customer's connection

List payment methods

Get a quote

Read the customer's credentials

Auth (email/OTP)

Set up Apple Pay

Set up Google Pay

Set up the widget

Set up the buy frame

Set up the buy button

Add a card

Set up the Challenge frame

Get a transaction

List transactions

Delete a payment method

Inline components

Every frame also has a declarative component you can render directly in your JSX tree. Components are a good fit when you want a frame embedded in a custom screen. The three deprecated methods below have direct component replacements.

Deprecated method	Component replacement
`client.setupApplePay()`	`<MoonPayApplePayButton>`
`client.setupGooglePay()`	`<MoonPayGooglePayButton>`
`client.setupBuyButton()`	`<MoonPayBuyButton>`

Customers

Payments

Integration essentials

SDK Reference

Frames

Overview

Install

Register a crypto polyfill

Conventions

Provider + hook

`Result<T, E>`

Function reference

Mount the provider

Access the client with useMoonPay()

Check the customer's connection

Connect a customer

Reset the customer's connection

List payment methods

Get a quote

Read the customer's credentials

Auth (email/OTP)

Set up Apple Pay

Set up Google Pay

Set up the widget

Set up the buy frame

Set up the buy button

Add a card

Set up the Challenge frame

Get a transaction

List transactions

Delete a payment method

Inline components

Inline components overview

Auth (email/OTP) — inline

​Install

​Register a crypto polyfill

​Conventions

​Provider + hook

​Result<T, E>

​Function reference

Mount the provider

Access the client with useMoonPay()

Check the customer's connection

Connect a customer

Reset the customer's connection

List payment methods

Get a quote

Read the customer's credentials

Auth (email/OTP)

Set up Apple Pay

Set up Google Pay

Set up the widget

Set up the buy frame

Set up the buy button

Add a card

Set up the Challenge frame

Get a transaction

List transactions

Delete a payment method

​Inline components

Inline components overview

Auth (email/OTP) — inline

Install

Register a crypto polyfill

Conventions

Provider + hook

`Result<T, E>`

Function reference

Inline components