client.connect()

Render the connect flow in your UI.

Use client.connect() when you need to connect a customer’s MoonPay account in your app. This method mounts the co-branded connect flow into your UI 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 { createClient, type ConnectEvent } from "@moonpay/platform-sdk-web";

const client = createClient({ sessionToken: "c3N0XzAwMQ==" });

const connectResult = await client.connect({
  container: document.querySelector("#connectContainer"),
  onEvent: (event: ConnectEvent) => {
    switch (event.kind) {
      case "ready":
        // The UI is ready. Reveal the container if you hide 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;

// Remove the frame from the DOM now that the flow has completed:
// connectFrame.dispose();

The promise returned by client.connect() resolves after the customer completes the connect flow (or an error ends it). Track flow progress — including the moment the UI is ready to show — through onEvent, not by awaiting the promise.

---

Parameters

Field	Type	Required	Description
container	HTMLElement	✅	A connected DOM element to render the connect frame into.
theme	object		Optional appearance settings for the connect flow.
theme.appearance	"dark" | "light"		Force a specific appearance. If omitted, the frame uses the user’s system appearance.
onEvent	(event: ConnectEvent) => void		Callback invoked for connect flow events. See ConnectEvent.

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 from the DOM after the flow completes, call connectFrame.dispose() on the ConnectFrame returned from client.connect(). The frame handle only becomes available once the flow completes — the returned promise stays pending while the customer works through the flow.

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	✅	Removes the frame from the DOM and detaches event listeners.

ConnectError

ConnectError covers failures to mount the frame or complete the handshake. Per-flow failures inside the frame surface through the "error" event payload, ConnectEventError.

Field	Type	Required	Description
message	string	✅	A developer-friendly description of the failure (for example, a handshake timeout).

types.ts

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

type ConnectError = {
  message: string;
};

Resources

For full protocol details, see the connect frame reference.