MoonPay API nutzen: Fiat On- und Off-Ramp Integration

Die Umwandlung von Fiat in Krypto (On-Ramps) war früher mit erheblichem Aufwand verbunden: langwierige Compliance-Prozesse, Bankeinbindungen und fragmentierte KYC-Workflows. Mit der MoonPay-API lässt sich das auf eine einzige Integration reduzieren – Sie generieren eine signierte URL, binden das Widget in Ihre App ein und überlassen Kartenabwicklung, Banküberweisung, KYC und Auszahlung an die Wallet dem Service.

Teste Apidog noch heute

In diesem Leitfaden erhalten Sie eine Schritt-für-Schritt-Anleitung zur End-to-End-Nutzung der MoonPay-API: von der Konto-Einrichtung, Widget- und API-Integration, über die Erzeugung signierter URLs und Webhook-Verifizierung, bis hin zu Verkaufsfluss, NFT-Checkout und Compliance-Limits. Alle untenstehenden Requests wurden in der Sandbox getestet und sind im offiziellen MoonPay-Entwicklerportal dokumentiert. Sie können identische Calls in Apidog während der Entwicklung ausführen.

Wenn Sie noch Anbieter evaluieren, starten Sie mit unserem Überblick der besten Fiat On-Ramp und Off-Ramp APIs, um MoonPay im Vergleich zu Transak, Ramp und Stripe Crypto einzuschätzen. Für Verwahr-Infrastruktur lohnt sich auch unser Leitfaden zu Circle API.

TL;DR

• MoonPay ist eine regulierte Fiat-to-Krypto On-/Off-Ramp, genutzt von Wallets, NFT-Marktplätzen und Börsen in über 160 Ländern.
• Zwei Integrationswege: Ramps SDK/Widget (MoonPay-UI, schnellste Integration) oder direkte REST-API (maximale Kontrolle, eigene UI).
• Alle Widget-URLs müssen mit HMAC-SHA256 (Secret Key) signiert werden; unsignierte URLs werden abgelehnt.
• KYC, Kartenverarbeitung und Banking werden serverseitig von MoonPay abgewickelt; Status erhalten Sie über signierte Webhooks.
• Gebühren: 3,5-4,5% für Karten, günstiger bei Banküberweisung, zzgl. Netzwerkgebühr (alles transparent für den Endnutzer).
• Off-Ramp (Verkauf): Funktioniert wie der Kauf-Flow – signierte URL, Nutzer sendet Krypto, MoonPay zahlt Fiat aufs Bankkonto.

Was ist MoonPay?

MoonPay ist ein lizenziertes Zahlungsinstitut, das es ermöglicht, Kryptowährungen mit Karte, Banküberweisung, Apple Pay, Google Pay, SEPA und lokalen Zahlungsoptionen zu kaufen und zu verkaufen. Es ist als Geldtransmitter in den USA, mit E-Geld-Lizenz in der EU und Registrierungen in UK, Kanada und Australien aktiv – Sie müssen also selbst keine Zahlungsdienste-Lizenz erwerben, um Fiat-zu-Krypto in Ihrer App anzubieten.

Unterstützt werden über 110 Kryptowährungen auf mehr als 40 Netzwerken (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum) sowie NFT-Checkout. MoonPay ist z.B. direkt in MetaMask, Trust Wallet und OpenSea integriert.

Authentifizierung und Einrichtung

1. Partnerkonto eröffnen: moonpay.com/business
2. Nach Freischaltung erhalten Sie Sandbox- und Produktions-Schlüsselpaare:
   • Public Key: pk_test_...
   • Secret Key: sk_test_...

Tipp: Den Secret Key wie ein Datenbankpasswort behandeln – er signiert URLs und verifiziert Webhooks.

Umgebungsvariablen setzen:

export MOONPAY_API_KEY="pk_test_123..."
export MOONPAY_SECRET_KEY="sk_test_abc..."
export MOONPAY_BASE_URL="https://api.moonpay.com"

Die Sandbox bietet identische Endpunkte wie Produktion, aber mit Test-Transaktionen, die via Dashboard gesteuert werden können. Entwickeln und testen Sie komplett in der Sandbox und stellen Sie erst nach bestandener Compliance-Prüfung auf Produktion um.

Kern-Endpunkte

Die wichtigsten MoonPay-Endpoints sind: Währungen, Kurse, Transaktionen und Webhooks. Die vollständige Referenz finden Sie hier.

Unterstützte Währungen abfragen

Vor der UI-Implementierung die verfügbaren Währungen abfragen und ggf. nach Nutzerstandort filtern:

curl -X GET "https://api.moonpay.com/v3/currencies" \
  -H "Authorization: Api-Key $MOONPAY_API_KEY"

Antwort enthält u.a. code, name, type (crypto/fiat), minBuyAmount, maxBuyAmount und netzwerkspezifische Metadaten.

Echtzeitkurs abrufen

Teilen Sie dem User vorab exakt mit, wie viel Krypto er erhält (inkl. Gebühren):

curl -X GET "https://api.moonpay.com/v3/currencies/eth/buy_quote?apiKey=$MOONPAY_API_KEY&baseCurrencyAmount=100&baseCurrencyCode=usd" \
  -H "Content-Type: application/json"

Antwort: quoteCurrencyAmount, feeAmount, networkFeeAmount, totalAmount. Kurs bleibt ca. 60 Sekunden gültig.

Signierte Buy-Widget-URL erzeugen (Node.js)

Das Buy-Widget ist der schnellste Weg zur Integration. Erstellen Sie eine URL mit Query-Params, signieren Sie mit Ihrem Secret Key und leiten Sie den Nutzer weiter oder binden Sie sie im iFrame ein.

import crypto from "node:crypto";

function buildMoonPayBuyUrl({ walletAddress, currencyCode, baseAmount, email }) {
  const params = new URLSearchParams({
    apiKey: process.env.MOONPAY_API_KEY,
    currencyCode,
    walletAddress,
    baseCurrencyCode: "usd",
    baseCurrencyAmount: String(baseAmount),
    email,
    redirectURL: "https://yourapp.com/moonpay/complete",
  });

  const originalUrl = `https://buy.moonpay.com?${params.toString()}`;

  const signature = crypto
    .createHmac("sha256", process.env.MOONPAY_SECRET_KEY)
    .update(new URL(originalUrl).search)
    .digest("base64");

  return `${originalUrl}&signature=${encodeURIComponent(signature)}`;
}

Die Signatur bindet die Parameter an Ihr Konto. Details zu Parametern im Buy-Widget-Quickstart.

Webhook-Signaturen verifizieren

MoonPay sendet Statusupdates per Webhook (transaction_created, transaction_updated, etc.). Jeder Call enthält einen Header Moonpay-Signature-V2. Prüfen Sie die Signatur:

import crypto from "node:crypto";

export function verifyMoonPayWebhook(rawBody, header, secret) {
  const [tPart, sPart] = header.split(",");
  const timestamp = tPart.split("=")[1];
  const signature = sPart.split("=")[1];

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex"),
  );
}

Verwerfen Sie Anfragen, die älter als fünf Minuten sind. Die Webhook-Doku listet alle Events und Payloads.

Verkaufs- (Off-Ramp) Flow

Der Ablauf für den Verkauf spiegelt den Kauf wider. Erstellen Sie eine signierte URL (diesmal auf sell.moonpay.com), User wählt Asset/Betrag, MoonPay stellt die Einzahlungsadresse bereit und transferiert nach On-Chain-Bestätigung Fiat aufs Bankkonto.

const sellParams = new URLSearchParams({
  apiKey: process.env.MOONPAY_API_KEY,
  baseCurrencyCode: "eth",
  baseCurrencyAmount: "0.5",
  quoteCurrencyCode: "usd",
  refundWalletAddress: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbc",
});

const sellUrl = `https://sell.moonpay.com?${sellParams.toString()}`;
// genauso signieren wie die Buy-URL

refundWalletAddress ist für Rückabwicklungen essenziell.

NFT-Checkout

Um ein NFT direkt mit Karte zu kaufen, registrieren Sie das Listing bei MoonPay (oder nutzen eine Marktplatzintegration), dann generieren Sie eine signierte URL mit contractAddress, tokenId, listingId. MoonPay übernimmt Fiat- und On-Chain-Transfer in einem Schritt.

Häufige Fehler und Ratenlimits

Typische Integrationsfehler:

• 400 invalid_signature: Signatur stimmt nicht, i.d.R. durch Abweichungen in der URL-Encoding. Immer exakt die gesendete Query signieren.
• 403 geo_restricted: Nutzer-IP im nicht unterstützten Land. Prüfen Sie isAllowed vor Anzeige.
• 422 transaction_limit_exceeded: Tages-, Wochen- oder Monatslimits überschritten. Standard: $2.000/Tag, $10.000/Monat (vor erweitertem KYC).
• 429 rate_limited: Ca. 100 Anfragen/Minute pro API-Key. Aggressiv Listen/Kurse cachen.

Für den Status immer den Webhook verwenden, nicht die Browser-Weiterleitung. Auch bei Tab-Schließung wird die Transaktion via Webhook-Event final bestätigt.

Für Multi-Wallet-Support siehe unsere Anleitungen zu MetaMask API und beste Krypto-Wallet APIs. Für Compliance lesen Sie die beste KYC API Übersicht.

MoonPay-Preise

MoonPay berechnet eine Bearbeitungsgebühr plus Netzwerkgebühr, beides wird im Widget transparent angezeigt:

• Kartenkäufe: 3,5–4,5% vom Betrag, mind. $3.99
• Banküberweisung (ACH, SEPA, Open Banking): 1–1,9%, günstiger bei hohen Beträgen
• Netzwerkgebühr: Durchgereicht zum Selbstkostenpreis, je nach Chain/Auslastung
• Verkauf (Off-Ramp): Ähnliche Struktur, mit Auszahlungsgebühr je nach Bank

Partner-Umsatzbeteiligung wird ab höheren Volumen individuell verhandelt.

MoonPay mit Apidog testen

Fehler bei signierten URLs und HMAC-Webhooks sind die häufigste Stolperfalle. Mit Apidog importieren Sie die MoonPay OpenAPI, speichern Sandbox-Keys als Umgebungsvariablen und testen den vollen Flow (Kaufangebot, Status, Webhook-Test) ohne Coding im Backend.

Praktischer Workflow:

• Erstellen Sie separate Apidog-Umgebungen für sandbox und production
• Skripten Sie die Signaturerzeugung als Pre-Request-Hook mit dem obigen Node-Snippet
• Speichern Sie Beispiel-Transaktions-IDs als Variablen, um zwischen createTransaction und getTransactionStatus zu springen
• Bei Produktion: Kopieren Sie Roh-Webhooks in Apidog Mock-Server und testen Sie Ihren lokalen Endpoint mit echten Payloads
• Apidog herunterladen für Signier-Hooks, Mock-Server und Umgebungswechsler

FAQ

Brauche ich zusätzlich zu MoonPay einen eigenen KYC-Anbieter?

Nein. MoonPay übernimmt die Identitätsprüfung serverseitig; Ihre Anwendung sieht nie das ID-Dokument. Für Pre-KYC in anderen Produktbereichen siehe unseren KYC-API-Vergleich.

Kann ich MoonPay ohne das gebrandete Widget nutzen?

Ja, via direkte API oder Headless SDK. Dafür ist aber eine zusätzliche Compliance-Prüfung nötig, da viele Offenlegungspflichten im Widget-Flow abgedeckt werden. Die meisten Teams starten mit Widget und wechseln erst bei hohem Volumen.

Welche Länder unterstützt MoonPay?

Über 160 für Kauf, rund 50 für Verkauf. Die Verfügbarkeit von Währungen und Zahlungsmethoden variiert regional; der Currencies-Endpunkt gibt stets die aktuelle Matrix pro Standort zurück.

Wie lange dauert eine Transaktion?

Kartenkäufe in der Regel <5 Minuten. Banküberweisungen: 1–3 Werktage für Fiat-Clearing, danach Freigabe von Krypto. Verkauf: 1–3 Tage bis zur Bankauszahlung nach On-Chain-Bestätigung.

Was passiert, wenn Webhooks nicht zugestellt werden können?

MoonPay wiederholt die Zustellung mit exponentiellem Backoff bis zu 24 Stunden. Antworten Sie erst mit 2xx, wenn das Event persistiert ist; deduplizieren Sie via id, da Wiederholungen identische Payloads liefern.

Ist die Sandbox produktionsäquivalent?

Fast – Geo-Checks sind gelockert, KYC wird mit Testdaten simuliert, Transaktionen lassen sich via Dashboard in Zustände versetzen. Führen Sie vor Go-Live einen echten Test mit Produktions-Keys durch.