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.

Connect a customer’s MoonPay account so you can list payment methods, get executable quotes, and execute transactions. Before you start, review the requirements.

​
Prerequisites

  • A server that can create session tokens with your secret key.
  • A client that can render frames (SDK or manual integration).
Connecting is a one or two-step process depending on whether the customer is new or returning:
  • If the customer has never connected, render the co-branded connect frame.
  • If the customer has connected before, first check whether their connection is still valid. You only need to render UI again if the connection has expired.
For all cases, first create a session, then check if a connection exists. If a connection is required, initialize the connect flow.

​
Create a session

To initiate a session on your server, provide:
  1. A unique identifier from your system for the customer (externalCustomerId).
  2. The IP address of the customer’s device. This is used across frames to ensure the integrity of the session.
Once initiated, you receive a sessionToken to send to your frontend. 
// Server-side code example
const url = "https://api.moonpay.com/platform/v1/sessions";

const res = await fetch(url, {
  headers: {
    "Content-Type": "application/json",
    Authorization: "Api-Key sk_test_123",
  },
  method: "POST",
  body: JSON.stringify({
    externalCustomerId: "your_user_id",
    deviceIp: "...ip address from client",
  }),
});

console.log(await res.json());
Check the API reference for detailed usage.

​
Check connection

Using the sessionToken, check if the customer already has an active connection. No UI appears in this step, but it runs in a frame. You can check the session using the SDK or manually. The check frame always returns encrypted credentials. Hold them in memory only and do not persist them, regardless of the status returned. For an active connection these are authenticated credentials. For connectionRequired, these are anonymous credentials whose clientToken you pass into the connect flow. 
import { createClient } from "@moonpay/platform";

// Create the client with your session token
const clientResult = createClient({
  sessionToken: "c3N0XzAwMQ==", // The session token from your server
});

if (!clientResult.ok) {
  // Handle error creating client
}

const client = clientResult.value;

// Check if the customer has an active connection
const connectionResult = await client.getConnection();

if (!connectionResult.ok) {
  // Handle error
}

console.log(connectionResult.value);
The SDK injects an invisible frame to check the connection. If you are integrating without the SDK, load the frame directly and listen for the postMessage events.

​
Low-friction authentication

You can simplify login for returning customers by passing the optional email and phoneNumber parameters when you create a session. If these values match an existing MoonPay account, the connect frame skips the full login and prompts the customer to enter an OTP code sent to their phone.

​
Connect flow

If you need to create or revalidate a connection, initialize the connect flow with the clientToken from the anonymous credentials returned by the check frame. The SDK provides hooks to coordinate rendering the connect UI (for example, to animate a modal or sheet). You can also do this manually. When the connect flow completes, replace the anonymous credentials from the check step with the authenticated credentials from the complete event. The resulting connection has one of the following statuses: active, pending, unavailable, or failed.
In mobile apps, present the connect flow as a full sheet. See presentation and appearance for UI guidance.
import { createClient, type ConnectEvent } from "@moonpay/platform";

// Create the client
const clientResult = createClient({
  sessionToken: "c3N0XzAwMQ==", // The session token from your server
});

if (!clientResult.ok) {
  // Handle error creating client
}

const client = clientResult.value;

// Initialize the connect flow
const connectResult = await client.connect({
  container: connectContainer, // DOM element to render the connect frame

  theme: { appearance: "dark" }, // Optional: force dark or light mode

  onEvent: (event: ConnectEvent) => {
    switch (event.kind) {
      case "ready":
        // The frame is ready and rendered
        break;

      case "complete":
        // The connection is complete
        console.log(event.connection);
        // { status: "active", customer: { id: "..." }, credentials: { accessToken: "...", clientToken: "..." } }

        // You can unmount the frame using the reference in the payload
        event.payload.frame.dispose();
        break;

      case "error":
        // Handle error
        console.error(event.payload.message);
        break;
    }
  },
});

// If there is an error setting up the connect frame, no events will be
// dispatched via the `onEvent` callback and you will receive an error here.
if (!connectResult.ok) {
  // Handle error
}

// If the frame is successfully mounted, the returned value provides a reference for disposal at any time.
connectResult.value.dispose();
When you receive the complete event, the payload includes authenticated client credentials and a customer object identifying the connected MoonPay customer. Discard any anonymous credentials from the check step and use the new ones instead. Use them to make scoped API calls from your frontend (for example, listing payment methods and getting quotes). See Pay with Apple Pay for a complete example flow.

​
Capabilities

The complete event also includes a capabilities object that describes regulatory requirements for the connected customer. You can use this to customize your UI before initiating a transaction; for example, determining whether a payment disclosure is required. 
{
  kind: "complete",
  connection: {
    status: "active",
    customer: {
      id: "Y3VzX2FiYzEyMw=="
    },
    credentials: {
      accessToken: "c2F0XzAwMQ==",
      clientToken: "c2N0XzAwMQ=="
    },
    capabilities: {
      ramps: {
        // No payment disclosure required for this customer
        requirements: {}
      }
    }
  },
  payload: {
    frame: {
      dispose: [Function]
    }
  }
}
If capabilities.ramps.requirements.paymentDisclosures is present, you must display the required disclosure to the customer before they can complete a transaction. See Going Live for the exact text to render and presentation requirements.
Client credentials should never be persisted and should only be held in memory as this could pose a security risk.

​
Connection statuses

​
Active

An active status means the connection is valid and can be used. Active connections typically remain live for 180 days without revalidation. If the connection expires, refresh it via the connect flow.

​
Unavailable

An unavailable status means the connection cannot be used at the current time. This typically occurs when a KYC-verified customer is using a device or application from a restricted location.

​
Pending

A pending status typically occurs for customers whose KYC decisions are delayed. Often these cases are resolved out of band and the customer can connect on a subsequent visit to your app.

​
Failed

A failed status is a terminal state. This usually happens if the customer fails KYC or cannot be onboarded to MoonPay. It can also happen if the customer rejects the connection. In these cases, direct the customer to an alternate flow in your app.

​
Connection required

The connectionRequired status is returned from the check frame as a signal to guide the customer through the full connect flow. This status is returned for new customers who have not connected to your app, or returning customers whose connections have expired. The response also includes anonymous credentials — keep them only in memory and use the clientToken to initialize the connect flow.