Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dev.moonpay.com/llms.txt

Use this file to discover all available pages before exploring further.

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;

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

​
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().

​
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.