client.getConnection()

Check whether the customer already has an active connection.

Use this method to check whether the current customer already has an active connection. If the customer is not connected (or the connection expired), run the connect flow with client.connect().

The SDK runs the check in a hidden frame, decrypts the returned credentials, and primes the client so that subsequent SDK calls (such as getPaymentMethods() or getQuote()) are authenticated automatically.

Get a connection

import { createClient } from "@moonpay/platform-sdk-web";

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

const result = await client.getConnection();

if (!result.ok) {
  // Handle error
  console.error(result.error.message);
  return;
}

switch (result.value.status) {
  case "active":
    console.log(result.value.customer.id);
    break;
  case "connectionRequired":
    // Render the connect flow with client.connect().
    break;
  case "termsAcceptanceRequired":
    // Show your own Terms of Use UI, then create a new session with
    // termsAcceptedAt and relaunch the flow.
    break;
  case "pending":
    // KYC decision delayed. Retry later.
    break;
  case "failed":
    console.error(result.value.reason);
    break;
  case "unavailable":
    // Restricted location. Surface a fallback experience.
    break;
}

---

Parameters

client.getConnection() takes an optional options object.

Field	Type	Required	Description
skipKyc	boolean		Pass true for headless/Customer API integrations so the check skips KYC-based statuses: the result won’t resolve to "pending" or "failed" due to KYC alone. "termsAcceptanceRequired" is still surfaced (legal requirements can’t be skipped). Defaults to false.

Result

client.getConnection() returns a Result<Connection, GetConnectionError>.

Result envelope

Result<Connection, GetConnectionError>

Field	Type	Required	Description
ok	boolean	✅	Whether the operation succeeded.
value	Connection		Present when ok is true.
error	GetConnectionError		Present when ok is false.

Connection

Connection is a discriminated union over status. The fields present depend on the status:

Variant	Fields	Description
"active"	status, customer, credentials, capabilities	The customer is connected. The SDK has already decrypted credentials internally — you do not need to send the credentials string anywhere.
"connectionRequired"	status, credentials, capabilities?, mismatch?	The customer needs to complete the connect flow. The SDK has decrypted the anonymous tokens internally; capabilities is present when guest checkout is enabled for the partner. mismatch is present and true when the session’s email and phone number resolve to different MoonPay customers.
"termsAcceptanceRequired"	status	The customer has no valid Terms of Use attestation on file (headless/Customer API partners). Display the Terms of Use yourself, pass the acceptance timestamp as termsAcceptedAt when you create a new session (POST /platform/v1/sessions), and relaunch the flow. Requires the Identity or Guest Checkout account capability.
"pending"	status	The KYC decision is delayed and may resolve on a subsequent visit.
"failed"	status, reason	Terminal failure (for example, KYC rejection).
"unavailable"	status	The customer is in a restricted location.

Fields

Field	Type	Required	Description
status	"active" | "connectionRequired" | "termsAcceptanceRequired" | "pending" | "failed" | "unavailable"	✅	The connection status.
customer	object		Present when status is "active". Contains the connected MoonPay customer.
customer.id	string		The MoonPay customer identifier.
customer.country	string		The customer’s ISO 3166-1 alpha-3 residential country code (for example, "USA" or "FRA"). Use this to determine which payment disclosures apply.
customer.administrativeArea	string		The customer’s state or province code, included when disclosures apply at the subdivision level (for example, "NY" or "WA").
customer.area	string		The broader regulatory area for the customer’s country, when applicable. Currently "EEA".
credentials	string		Present when status is "active" or "connectionRequired". A base64-encoded, X25519+AES-GCM-encrypted token blob. The SDK decrypts this internally — you don’t need to handle it directly.
capabilities	CustomerCapabilities		Required on "active"; optional on "connectionRequired" (present when guest checkout is enabled for the partner).
mismatch	boolean		Present only when status is "connectionRequired" and the session’s email and phone number resolve to different MoonPay customers (a conflict). When true, route the customer through the connect flow before rendering payment UI such as Apple Pay. Absent when there is no conflict — never false.
reason	string		Present only when status is "failed". Developer-friendly failure details.

CustomerCapabilities

Capabilities and regulatory requirements for the customer.

Field	Type	Required	Description
ramps	RampsCapability		Capabilities for buy and sell flows.
guestCheckout	RampsCapability		Capabilities for the guest checkout flow. Present when guest checkout is enabled for the partner and the session is a guest-checkout session.

RampsCapability

Field	Type	Required	Description
requirements	RampsRequirements	✅	Regulatory requirements that apply to ramps for the customer. paymentDisclosures is deprecated — read geography from customer.country, customer.administrativeArea, and customer.area instead.

types.ts

type Customer = {
  id: string;
  country?: string;
  administrativeArea?: string;
  area?: string;
};

type Connection =
  | {
      status: "active";
      customer: Customer;
      credentials: string;
      capabilities: CustomerCapabilities;
    }
  | {
      status: "connectionRequired";
      credentials: string;
      capabilities?: CustomerCapabilities;
      mismatch?: boolean;
    }
  | { status: "termsAcceptanceRequired" }
  | { status: "pending" }
  | { status: "failed"; reason: string }
  | { status: "unavailable" };

GetConnectionError

GetConnectionError covers failures to run the connection check (for example, a frame handshake timeout).

Field	Type	Required	Description
message	string	✅	A developer-friendly description of the failure.