Skip to main content
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.
FieldTypeRequiredDescription
skipKycbooleanPass 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>
FieldTypeRequiredDescription
okboolean✅Whether the operation succeeded.
valueConnectionPresent when ok is true.
errorGetConnectionErrorPresent when ok is false.

​
Connection

Connection is a discriminated union over status. The fields present depend on the status:
VariantFieldsDescription
"active"status, customer, credentials, capabilitiesThe 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"statusThe 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"statusThe KYC decision is delayed and may resolve on a subsequent visit.
"failed"status, reasonTerminal failure (for example, KYC rejection).
"unavailable"statusThe customer is in a restricted location.

​
Fields

FieldTypeRequiredDescription
status"active" | "connectionRequired" | "termsAcceptanceRequired" | "pending" | "failed" | "unavailable"✅The connection status.
customerobjectPresent when status is "active". Contains the connected MoonPay customer.
customer.idstringThe MoonPay customer identifier.
customer.countrystringThe customer’s ISO 3166-1 alpha-3 residential country code (for example, "USA" or "FRA"). Use this to determine which payment disclosures apply.
customer.administrativeAreastringThe customer’s state or province code, included when disclosures apply at the subdivision level (for example, "NY" or "WA").
customer.areastringThe broader regulatory area for the customer’s country, when applicable. Currently "EEA".
credentialsstringPresent 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.
capabilitiesCustomerCapabilitiesRequired on "active"; optional on "connectionRequired" (present when guest checkout is enabled for the partner).
mismatchbooleanPresent 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.
reasonstringPresent only when status is "failed". Developer-friendly failure details.

​
CustomerCapabilities

Capabilities and regulatory requirements for the customer.
FieldTypeRequiredDescription
rampsRampsCapabilityCapabilities for buy and sell flows.
guestCheckoutRampsCapabilityCapabilities for the guest checkout flow. Present when guest checkout is enabled for the partner and the session is a guest-checkout session.

​
RampsCapability

FieldTypeRequiredDescription
requirementsRampsRequirements✅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).
FieldTypeRequiredDescription
messagestring✅A developer-friendly description of the failure.