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

FieldTypeRequiredDescription
containerHTMLElement✅A connected DOM element to render the connect frame into.
themeobjectOptional 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) => voidCallback 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.
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 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.
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✅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.
FieldTypeRequiredDescription
messagestring✅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.