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 submit attestation via the
    // Terms attestation API and retry.
    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 / Identity 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?The customer needs to complete the connect flow. The SDK has decrypted the anonymous tokens internally; capabilities is present when Apple Pay 1TAP is configured for the partner.
"termsAcceptanceRequired"statusThe customer has no valid Terms of Use attestation on file (headless/Identity API partners). Display the Terms of Use yourself, submit attestation via POST /platform/v1/terms/attestations, and retry.
"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 Apple Pay 1TAP is configured for the partner).
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.
oneTapApplePayRampsCapabilityCapabilities for the Apple Pay 1TAP flow. Present when 1TAP is enabled for the partner and customer.

​
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;
    }
  | { 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.