Introduction

Build fiat->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.

This integration is currently in preview and subject to change.

Getting started

Connect a customer

Connect a customer’s MoonPay account so you can list payment methods, get quotes, and execute transactions.

Read the guide

Execute a transaction

Set up a payment method (like Apple Pay) and execute a transaction in your UI.

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

1. 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/session";
   
   const res = await fetch(url, {
     headers: {
       "Content-Type": "application/json",
       Authorization: "Api-Key sk_test_123",
     },
     method: "POST",
     body: JSON.stringify({
       externalCustomerId: "your_user_id",
       deviceIp: "...ip address from client",
     }),
   });
   
   console.log(await res.json());
   
2. 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";
   
   // Create the client with your session token
   const clientResult = createClient({
     sessionToken: "c3N0XzAwMQ==", // The session token from your server
   });
   
   if (!clientResult.ok) {
     // Handle error creating client
   }
   
   const client = clientResult.value;
   
   // Check if the customer has an active connection
   const connectionResult = await client.getConnection();
   
   if (!connectionResult.ok) {
     // Handle error
   }
   
   console.log(connectionResult.value);
   
3. 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 with detailed fees and limits for transactions.

   Get quotes

   const quoteResult = await client.getQuote({
     source: "USD",           // The fiat currency for payment
     destination: "ETH",      // The crypto the customer will receive
     sourceAmount: "100.00",  // The amount to purchase
     walletAddress: "0x...",  // The destination wallet address
     paymentMethod: "apple_pay",
   });
   
   if (!quoteResult.ok) {
     // Handle error
   }
   
   console.log(quoteResult.value);
   // { signature: "...", expiresAt: "2026-01-12T14:45:00Z", ... }
   
5. Once you have a quote, execute the transaction.

   Pay with Apple Pay

   import type { ApplePayEvent } from "@moonpay/platform";
   
   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
   }