Introduction

Build fiat-to-crypto experiences with headless payments. You control the user experience while MoonPay handles compliance, risk, and fraud.

Welcome to the MoonPay Platform

Use the MoonPay Platform APIs, SDKs, and frames to build crypto ramps directly in your app. Before you start, review the requirements and core concepts.

Getting started

Choose an onboarding path

Compare hosted onboarding, onboarding via API, and guest checkout, and pick the path that fits your app.

Read the guide

Hosted onboarding

The hosted path: MoonPay’s co-branded connect frame handles login and the full KYC flow.

Read the guide

Onboarding via API

The API-driven path: capture KYC data in your own screens and submit it with the Customer API.

Read the guide

Guest checkout

The deferred path: new customers buy instantly, with verification stepped up at purchase time.

Read the guide

Frames

Embed headless and co-branded UI in your app.

Read more

API reference

Explore the Platform API endpoints and parameters.

Read more

Quickstart

The quickstart below shows the fastest path, hosted onboarding with Apple Pay. For the alternatives, see Choose an onboarding path.

1. Get a session token

   Create a session token on your server and send the token to your frontend.

   Create session token

   // Server-side code example
   const url = "https://api.moonpay.com/platform/v1/sessions";
   
   const res = await fetch(url, {
     headers: {
       "Content-Type": "application/json",
       "X-Api-Key": "sk_test_123",
     },
     method: "POST",
     body: JSON.stringify({
       externalCustomerId: "your_user_id",
       deviceIp: "...ip address from client",
     }),
   });
   
   console.log(await res.json());
   

   {
     "sessionToken": "c3N0XzAwMQ=="
   }
   
2. Connect a customer

   On your frontend, check whether the customer has an active connection. If they do, you receive credentials for the next steps.

   Check the connection

   import { createClient } from "@moonpay/platform-sdk-web";
   
   // Create the client with your session token
   const client = createClient({
     sessionToken: "c3N0XzAwMQ==", // The session token from your server
   });
   
   // Check if the customer has an active connection
   const connectionResult = await client.getConnection();
   
   if (!connectionResult.ok) {
     // Handle error
   }
   
   console.log(connectionResult.value);
   

   {
     status: "active",
     customer: {
       id: "Y3VzX2FiYzEyMw=="
     },
     // Encrypted credentials — the SDK decrypts and stores them internally
     credentials: "ZW5jXzAwMQ==",
     capabilities: {}
   }
   

   {
     status: "connectionRequired",
     // Encrypted credentials — the SDK decrypts and stores them internally
     credentials: "ZW5jXzAwMQ=="
   }
   
3. List payment methods

   List the payment methods available to the customer at the current time.

   List payment methods

   // After connecting, list available payment methods
   const paymentMethodsResult = await client.getPaymentMethods();
   
   if (!paymentMethodsResult.ok) {
     // Handle error
   }
   
   console.log(paymentMethodsResult.value);
   // [{ type: "apple_pay", capabilities: {...}, availability: {...} }, ...]
   
4. Get quotes

   Get quotes with detailed fees and limits for transactions.

   Get quotes

   const quoteResult = await client.getQuote({
     source: { asset: { code: "USD" }, amount: "100.00" }, // The fiat currency and amount to pay
     destination: { asset: { code: "ETH" } }, // The crypto the customer will receive
     wallet: { address: "0x..." }, // The destination wallet address
     paymentMethod: { type: "apple_pay" },
   });
   
   if (!quoteResult.ok) {
     // Handle error
   }
   
   console.log(quoteResult.value);
   // { signature: "...", expiresAt: "2026-01-12T14:45:00Z", ... }
   
5. Execute headless payments

   Once you have a quote, execute the transaction.

   Pay with Apple Pay

   import type { ApplePayEvent } from "@moonpay/platform-sdk-web";
   
   const paymentButtonContainer = document.querySelector("#payment");
   
   const setupApplePayResult = await client.setupApplePay({
     quote: quoteResult.value.signature, // The quote signature
     container: paymentButtonContainer,
   
     onEvent: (event: ApplePayEvent) => {
       switch (event.kind) {
         case "ready":
           // Reveal the button
           paymentButtonContainer.style.opacity = "1";
           break;
   
         case "complete":
           // The transaction is executing. Use polling and/or webhooks to track final status.
           console.log(event.payload.transaction);
           // { id: "txn_01", status: "pending" }
           break;
   
         case "quoteExpired":
           // Fetch a new quote and update the frame
           // event.payload.setQuote(newQuote.signature);
           break;
       }
     },
   });
   
   if (!setupApplePayResult.ok) {
     // Handle error
   }