client.connect()

Render the connect flow in your app.

Use client.connect() when you need to connect a customer’s MoonPay account in your app. The provider presents the connect flow in a full-screen native modal with a slide animation and streams lifecycle events through onEvent.

If you want the full end-to-end flow (create session → check connection → connect), start with the Connect a customer guide.

For UI recommendations, see Presentation and appearance.

Connect a customer

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

export function ConnectScreen() {
  const { client } = useMoonPay();

  const startConnect = async () => {
    const connectResult = await client.connect({
      onEvent: (event: ConnectEvent) => {
        switch (event.kind) {
          case "ready":
            // The UI is ready. Reveal the surface if you hid it while loading.
            break;
          case "complete":
            // event.payload is the Connection — same shape as client.getConnection() returns.
            if (event.payload.status === "active") {
              console.log(event.payload.customer.id);
            }
            break;
          case "error":
            // event.payload has a `code` discriminator. On validationError it carries
            // a list of field-level errors; on generic it may carry a developer message.
            console.error(event.payload);
            break;
        }
      },
    });

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

    const connectFrame = connectResult.value;

    // You can dispose the frame at any time:
    // connectFrame.dispose();
  };

  // ...
}

---

Parameters

Field	Type	Required	Description
theme	object		Optional appearance settings for the connect flow.
theme.appearance	"dark" | "light"		Force a specific appearance. If omitted, the frame uses the system appearance.
onEvent	(event: ConnectEvent) => void		Callback invoked for connect flow events. See ConnectEvent.

The provider renders the connect frame in a full-screen modal automatically. You don’t need to pass a container.

ConnectEvent

onEvent receives events as the connect flow progresses. Use event.kind to decide how to handle each event.

kind	Payload	When you receive it
"ready"	—	The connect UI is rendered and ready to be shown.
"complete"	Connection	The customer completed the connect flow. Same shape as client.getConnection().
"error"	ConnectEventError	The flow encountered an error.

To remove the frame after the flow completes, call connectFrame.dispose() on the ConnectFrame returned from client.connect().

ConnectEventError

The error event payload comes from the underlying connect frame. It is discriminated by code.

Field	Type	Required	Description
code	"validationError" | "generic"	✅	The error category.
errors	ConfigValidationFieldError[]		Present when code is "validationError". Field-level errors describing which inputs (such as the session token) failed validation.
message	string		Present on "generic" errors. Developer-friendly details.

ConfigValidationFieldError entries have a code of "invalidSessionToken", "invalidClientToken", or "invalidPublicKey", plus a developer-facing message.

types.ts

type ConfigValidationFieldError = {
  code: "invalidSessionToken" | "invalidClientToken" | "invalidPublicKey";
  message: string;
};

type ConnectEventError =
  | { code: "validationError"; errors: ConfigValidationFieldError[] }
  | { code: "generic"; message?: string };

Result

client.connect() returns a Result<ConnectFrame, ConnectError>.

Result envelope

Result<ConnectFrame, ConnectError>

Field	Type	Required	Description
ok	boolean	✅	Whether the operation succeeded.
value	ConnectFrame		Present when ok is true.
error	ConnectError		Present when ok is false.

ConnectFrame

Field	Type	Required	Description
dispose	() => void	✅	Unmounts the frame and detaches event listeners.

ConnectError

ConnectError covers failures to mount the frame or complete the handshake, and customer dismissal. Per-flow failures inside the frame surface with full details through the "error" event payload, ConnectEventError; the method then resolves with a generic ConnectError.

Field	Type	Required	Description
message	string	✅	A developer-friendly description of the failure. "Connect flow dismissed" when the customer closes the modal before completing (including mid-loading).

types.ts

type ConnectFrame = {
  dispose: () => void;
};

type ConnectError = {
  message: string;
};

Resources

For full protocol details, see the connect frame reference.