Skip to main content
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

FieldTypeRequiredDescription
themeobjectOptional 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) => voidCallback 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.
kindPayloadWhen you receive it
"ready"—The connect UI is rendered and ready to be shown.
"complete"ConnectionThe customer completed the connect flow. Same shape as client.getConnection().
"error"ConnectEventErrorThe 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.
FieldTypeRequiredDescription
code"validationError" | "generic"✅The error category.
errorsConfigValidationFieldError[]Present when code is "validationError". Field-level errors describing which inputs (such as the session token) failed validation.
messagestringPresent 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>
FieldTypeRequiredDescription
okboolean✅Whether the operation succeeded.
valueConnectFramePresent when ok is true.
errorConnectErrorPresent when ok is false.

​
ConnectFrame

FieldTypeRequiredDescription
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.
FieldTypeRequiredDescription
messagestring✅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.