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 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 WebView, decrypts the returned credentials, and primes the client so that subsequent SDK calls (such as getPaymentMethods() or getQuote()) are authenticated automatically.
import { useMoonPay } from "@moonpay/platform-sdk-react-native";
export function ConnectionGate() {
const { client } = useMoonPay();
const checkConnection = async () => {
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;
}
};
// ...
}
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? | 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" | status | The 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" | 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. |
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 Apple Pay 1TAP is configured for the partner). |
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. |
oneTapApplePay | RampsCapability | | Capabilities for the Apple Pay 1TAP flow. Present when 1TAP is enabled for the partner and customer. |
RampsCapability
| Field | Type | Required | Description |
|---|
requirements | RampsRequirements | ✅ | Regulatory requirements that apply to ramps for the customer. Includes paymentDisclosures when the jurisdiction requires it. |
type Connection =
| {
status: "active";
customer: { id: string };
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).
| Field | Type | Required | Description |
|---|
message | string | ✅ | A developer-friendly description of the failure. |
