Skip to main content
MoonPay always decides what verification a customer needs. The connection status, the customer’s kyc.status and requirements, and the session’s capabilities tell you exactly what is outstanding. You choose who renders the UI that captures it: MoonPay, your own screens, or no one until a purchase demands it.
If you want to…ChooseYou buildMoonPay renders
Ship fastest, with MoonPay handling onboarding UIHosted onboarding (connect flow)A session server and one embedded frameLogin and the full KYC flow
Own the onboarding UX end to end, or reuse KYC data you already captureOnboarding via API (Customer API)Your own KYC screens and API callsAn OTP login frame and fallback challenges only
Let new customers buy instantly with no upfront accountGuest checkoutPayment UI onlyThe payment sheet and step-up challenges

​
Every path shares the same backbone

Whichever path you choose, the integration follows the same sequence:
  1. Create a session on your server with your secret key.
  2. Check the connection in an invisible frame on your client.
  3. Route on the returned status and capabilities. This is the only point where the paths diverge.
  4. Accept payments with the payment method that fits your app.
Every path also shares the same fallback. When MoonPay needs more from the customer than the current step captures, you receive a challenge URL and render the hosted Challenge frame. See Handle challenges.

​
Hosted onboarding

Hosted onboarding is the fastest path to production. When the connection check returns connectionRequired, you render the co-branded connect frame. MoonPay guides the customer through login and the full KYC flow. When the flow completes, you receive authenticated credentials for payment calls. You build no verification UI. Follow the Hosted onboarding guide for the full walkthrough.

​
Onboarding via API

You keep onboarding in your own screens and drive verification through the Customer API. The Auth frame handles login only: the customer verifies a one-time passcode (OTP) and you receive authenticated credentials, with no KYC UI. From there you read kyc.status and its requirements, capture the outstanding data in your own screens, and submit it with the API. The fields and documents each country requires live in KYC data requirements. Follow the Onboarding via API guide for the full walkthrough.

​
Guest checkout

Guest checkout defers verification until a purchase requires it. You pass the customer’s email, phone number, and terms acceptance when you create the session. MoonPay creates a guest account at transaction time. When a purchase needs identity confirmation or more details, the payment frame emits a step-up challenge for you to render. Availability constraints apply: the guestCheckout capability appears on the connection only for enabled accounts and supported regions. Returning customers are recognized and connect instead. Follow Guest checkout for the full walkthrough.

​
Combine paths

You are not locked into one path:
  • Guests upgrade to full accounts through the connect flow. Limits lift on the same account, with no migration.
  • The API-driven path falls back to a hosted challenge when the submitted data alone isn’t enough. You render the challenge URL and the customer finishes verification in MoonPay’s UI.
  • You can run different paths on different surfaces of your app. For example, use hosted onboarding in your consumer app and onboarding via API in an embedded flow.

​
Next steps

Hosted onboarding

Build the hosted path: one co-branded frame for login and KYC.

Onboarding via API

Build the API-driven path: your screens, MoonPay’s verification decisions.

Guest checkout

Build the deferred path: instant purchases with step-up challenges.