MoonPayProvider

<MoonPayProvider> initializes the SDK with a sessionToken and renders MoonPay frames as react-native-webview instances when you call SDK methods. Wrap the part of your app that needs access to the client.

App.tsx

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

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

Read the client from descendant components with useMoonPay().

Props

Property	Type	Required	Description
`sessionToken`	`string`		The sessionToken created on your server. Optional — omit it and call `initialize()` once you have the token. When set, the prop takes precedence over an imperatively-set token.
`children`	`ReactNode`	✅	Your app tree. Components below the provider can call `useMoonPay()`.
`apiBaseUrl`	`string`		Override the MoonPay Platform API base URL. Defaults to production. Use this only when MoonPay support has asked you to point at a non-production environment.
`frameBaseUrl`	`string`		Override the MoonPay frame base URL. Defaults to production. Use this only when MoonPay support has asked you to point at a non-production environment.

Providing the session token later

The sessionToken prop is optional. If you don’t have the token when the provider mounts — for example, you fetch it from your server after the customer signs in — mount <MoonPayProvider> without it and call initialize() once the token is available.

App.tsx

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

export default function App() {
  return (
    <MoonPayProvider>
      <YourApp />
    </MoonPayProvider>
  );
}

SignInScreen.tsx

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

export function SignInScreen() {
  const { initialize } = useMoonPay();

  const handleSignIn = async () => {
    const sessionToken = await fetchSessionTokenFromYourServer();
    initialize(sessionToken);
  };

  // ...
}

The client that carries the new token becomes available on the next render, so drive your connection flow from a component that reads isInitialized rather than calling a method on a client you captured before initialize(). Calling a connection method before a token is set returns an err() result.

If you pass the sessionToken prop and also call initialize(), the prop wins — pick one approach. Calling initialize() again replaces the token (for example, after a refresh or when switching accounts) and clears any credentials cached from the previous session.

Frame rendering

When you call a method that opens a visible frame — such as client.connect(), client.setupWidget(), or client.setupAddCard() — the provider presents it in a full-screen native Modal with a slide animation. Multiple frames stack naturally: for example, a challenge frame appears on top of an active widget. On Android, the hardware back button dismisses the top frame and disposes it. Hidden utility frames (used by client.getConnection(), client.setupBuy(), and client.resetConnection()) render as zero-size siblings with no visible impact on your layout.

Layout

<MoonPayProvider sessionToken="c3N0XzAwMQ==">
  <YourAppShell />
  {/* Hidden utility frames are mounted here as zero-size siblings.
      Visible frames appear in full-screen modals above your content. */}
</MoonPayProvider>

Client methods

The hook exposes a client object with every integration method:

Overview

Customers

Payments

Integration essentials

SDK Reference

Frames

Props

Providing the session token later

Frame rendering

Client methods

​Props

​Providing the session token later

​Frame rendering

​Client methods

Props

Providing the session token later

Frame rendering

Client methods