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

Die Umwandlung von Fiat in Krypto (On-Ramps) bedeutete früher wochenlange Compliance-Formalitäten, Bankbeziehungen und KYC-Anbieter, die notdürftig zusammengeflickt wurden. Die MoonPay-API reduziert diesen Aufwand auf eine einzige Integration: Sie generieren eine signierte URL, fügen ein Widget in Ihre App ein, und MoonPay kümmert sich um die Kartenabwicklung, Banküberweisungen, Identitätsprüfung und Auszahlungen an die Wallet des Benutzers.

Dieser Leitfaden führt Sie durch die end-to-end Nutzung der MoonPay-API: Einrichtung des Partnerkontos, Widget vs. direkte API, Erstellung signierter URLs, Webhook-Verifizierung, der Verkaufsfluss, NFT-Checkout und die Compliance-Limits, die Sie berücksichtigen müssen. Jede unten aufgeführte Anfrage wurde in der Sandbox getestet und im offiziellen MoonPay-Entwicklerportal dokumentiert. Sie können dieselben Aufrufe in Apidog ausführen, während Sie entwickeln.

button

Wenn Sie noch Anbieter vergleichen, beginnen Sie mit unserer Zusammenfassung der besten Fiat On-Ramp und Off-Ramp APIs, um zu sehen, wie MoonPay im Vergleich zu Transak, Ramp und Stripe Crypto abschneidet. Entwickler, die sich mit verwahrender Infrastruktur befassen, sollten auch wie man die Circle API verwendet lesen, um einen Überblick über die USDC-Seite des Stacks zu erhalten.

TL;DR

MoonPay ist eine regulierte Fiat-to-Krypto On-Ramp und Off-Ramp, die von Wallets, NFT-Marktplätzen und Börsen in über 160 Ländern genutzt wird.
Zwei Integrationspfade: das Ramps SDK/Widget (am schnellsten, MoonPay-gehostete Benutzeroberfläche) oder direkte REST-API (volle Kontrolle, Sie erstellen die Benutzeroberfläche).
Alle Widget-URLs müssen mit HMAC-SHA256 unter Verwendung Ihres Secret Keys signiert werden; unsignierte URLs werden in der Produktion abgelehnt.
KYC, Kartenverarbeitung und Bankverbindungen werden serverseitig von MoonPay abgewickelt; Sie erhalten den Status über Webhooks, die mit demselben HMAC-Muster signiert sind.
Die Preisgestaltung umfasst eine Bearbeitungsgebühr (3,5%-4,5% für Karten, niedriger für Banküberweisungen) zuzüglich der zugrunde liegenden Netzwerkgebühr, die dem Benutzer transparent weitergegeben wird.
Der Off-Ramp (Verkaufs)-Fluss spiegelt den Kauf-Fluss wider: signierte URL, Benutzer sendet Krypto an eine Einzahlungsadresse, MoonPay überweist Fiat auf das Bankkonto des Benutzers.

Was ist MoonPay?

MoonPay ist ein lizenziertes Zahlungsunternehmen, das Ihren Benutzern den Kauf und Verkauf von Kryptowährungen mit Karten, Banküberweisungen, Apple Pay, Google Pay, SEPA und lokalen Zahlungsoptionen ermöglicht. Es operiert als Geldtransaktionsdienstleister in den USA, verfügt über eine E-Geld-Lizenz in der EU und ist in Großbritannien, Kanada und Australien registriert. Der praktische Effekt: Sie müssen kein Geldtransmitter werden, um eine Karte zu akzeptieren und ETH an die Wallet eines Benutzers zu liefern.

Die Plattform deckt über 110 Kryptowährungen auf über 40 Netzwerken (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum) ab, plus NFT-Checkout. Es ist die On-Ramp in MetaMask, Trust Wallet und OpenSea.

Authentifizierung und Einrichtung

Registrieren Sie sich für ein Partnerkonto unter moonpay.com/business. Nach Genehmigung erhalten Sie zwei Schlüsselpaare: Sandbox und Produktion. Jedes Paar besteht aus einem Public Key (pk_test_...) und einem Secret Key (sk_test_...). Behandeln Sie den Secret Key wie ein Datenbankpasswort; er signiert jede URL und verifiziert jeden Webhook.

Stellen Sie sie in Ihrer Umgebung ein:

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

Die Sandbox verfügt über dieselben Endpunkte wie die Produktion, gibt jedoch Testtransaktionen zurück, die Sie über das Dashboard zwischen den Status wechseln können. Verwenden Sie sie für den vollständigen "Happy Path" und wechseln Sie dann zu den Produktionsschlüsseln, sobald Ihre Compliance-Prüfung mit MoonPay abgeschlossen ist.

Kern-Endpunkte

MoonPay stellt einige Endpunktgruppen bereit, die Sie am häufigsten verwenden werden: Währungen, Kurse, Transaktionen und Webhooks. Die vollständige REST-Referenz listet jede Ressource auf.

Unterstützte Währungen auflisten

Bevor Sie einen Wähler erstellen, rufen Sie die Live-Liste ab. Die Verfügbarkeit variiert je nach Land, daher sollten Sie nach der IP-Adresse oder dem angegebenen Standort des Benutzers filtern.

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

Die Antwort gibt ein Array mit code, name, type (crypto oder fiat), minBuyAmount, maxBuyAmount und netzwerkspezifischen Metadaten für Tokens zurück, die auf mehreren Ketten existieren.

Einen Echtzeitkurs abrufen

Kurse teilen dem Benutzer genau mit, wie viel Krypto er erhalten wird, bevor er sich verpflichtet. Gebühren sind enthalten.

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"

Sie erhalten quoteCurrencyAmount, feeAmount, networkFeeAmount und totalAmount zurück. Speichern Sie den Kurs für die wenigen Sekunden, die der Benutzer zum Klicken benötigt; MoonPay hält ihn für etwa 60 Sekunden ein.

Das Buy-Widget ist der schnellste Weg zu einer funktionierenden Integration. Sie erstellen eine URL mit Abfrageparametern, signieren sie mit Ihrem Secret Key und leiten entweder den Benutzer um oder laden sie in einem iFrame. Hier ist die Node-Version:

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)}`;
}

Geben Sie diese URL an den Benutzer weiter. Die Signatur bindet die Parameter an Ihr Konto, sodass ein bösartiger Client die walletAddress nicht tauschen oder den Betrag ändern kann, ohne sie ungültig zu machen. Der Buy-Widget-Quickstart dokumentiert jeden unterstützten Parameter.

Webhook-Signaturen verifizieren

MoonPay sendet Lebenszyklusereignisse an Ihren Endpunkt: transaction_created, transaction_updated, transaction_failed und Sell/NFT-Varianten. Jede Anfrage enthält einen Moonpay-Signature-V2-Header, den Sie überprüfen müssen, bevor Sie der Nutzlast vertrauen.

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"),
  );
}

Lehnen Sie Anfragen ab, die älter als fünf Minuten sind, um Replay-Angriffe zu verhindern. Die Webhook-Referenz listet jeden Ereignistyp und die Nutzlastform auf.

Verkaufs- (Off-Ramp) Fluss

Der Verkaufsfluss spiegelt den Kauf wider. Sie erstellen eine signierte URL, die auf sell.moonpay.com verweist, der Benutzer wählt eine Krypto und einen Betrag aus, MoonPay generiert eine Einzahlungsadresse, und der Benutzer sendet Gelder von seiner Wallet. Sobald die Transaktion in der Kette bestätigt ist, überweist MoonPay Fiat auf das verknüpfte Bankkonto des Benutzers.

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()}`;
// sign the same way as the buy URL

refundWalletAddress ist wichtig: Wenn der Benutzer das falsche Asset sendet oder die Transaktion KYC nicht besteht, sendet MoonPay die Gelder dorthin zurück.

NFT-Checkout

Der NFT-Checkout ermöglicht es einem Benutzer, ein gelistetes NFT mit einer Karte zu kaufen. Sie registrieren das Listing bei MoonPay (oder verwenden eine unterstützte Marktplatzintegration) und generieren dann eine signierte URL mit contractAddress, tokenId und listingId. MoonPay wickelt die Fiat-Transaktion und die On-Chain-Übertragung in einem einzigen Fluss ab, was den Abbruch bei hochwertigen Primärverkäufen dramatisch reduziert.

Häufige Fehler und Ratenbegrenzungen

Die meisten Integrationsprobleme landen in einer kurzen Liste:

400 invalid_signature bedeutet, dass Ihre HMAC-Eingabe nicht mit der des Servers übereinstimmt. Die häufigste Ursache sind URL-Kodierungsunterschiede zwischen Ihrem Client und dem Signierer. Signieren Sie die exakte Abfragezeichenfolge, die Sie senden.
403 geo_restricted signalisiert, dass die IP-Adresse des Benutzers in einem Land liegt, das MoonPay für diese Währung nicht bedient. Überprüfen Sie das Feld isAllowed im Währungsobjekt, bevor Sie es rendern.
422 transaction_limit_exceeded bedeutet, dass der Benutzer tägliche, wöchentliche oder monatliche Limits überschritten hat. Kartenlimits liegen typischerweise bei 2.000 $/Tag und 10.000 $/Monat, bis der Benutzer eine erweiterte KYC abgeschlossen hat.
429 rate_limited wird bei etwa 100 Anfragen pro Minute pro API-Schlüssel an öffentlichen Endpunkten ausgelöst. Cachen Sie Währungslisten und Kurse aggressiv.

Vertrauen Sie für den Status dem Webhook, nicht dem Browser des Benutzers. Ein Benutzer, der den Tab vor der Weiterleitung schließt, hat immer noch eine gefüllte Wallet, sobald das transaction_updated-Ereignis mit status: completed ausgelöst wird.

Wenn Sie Multi-Wallet-Unterstützung aufbauen, passen unsere Anleitungen zur Nutzung der MetaMask API und die besten Krypto-Wallet APIs gut dazu. Für die Identitätsseite der Compliance sehen Sie sich unsere Zusammenfassung der besten KYC API an.

MoonPay-Preise

MoonPay berechnet eine Bearbeitungsgebühr plus die Netzwerkgebühr, beides wird dem Benutzer im Widget angezeigt:

Kartenkäufe: 3,5%-4,5% des Fiat-Betrags, mit einem Minimum von 3,99 $.
Banküberweisung (ACH, SEPA, Open Banking): 1%-1,9%, viel günstiger bei großen Beträgen.
Netzwerkgebühr: wird zum Selbstkostenpreis weitergegeben, variiert je nach Kette und Auslastung.
Verkaufsfluss: ähnliche Struktur, mit Auszahlungsgebühren je nach Zielbankverbindung.

Die Umsatzbeteiligung für Partner wird separat verhandelt, sobald das Volumen ansteigt. Hochvolumen-Integrationen erhalten typischerweise kundenspezifische Preise sowie einen engagierten Compliance-Ansprechpartner.

MoonPay mit Apidog testen

Signierte URLs und HMAC-Webhooks sind die beiden Stellen, an denen die meisten MoonPay-Integrationen scheitern, und beide sind in einem richtigen API-Client schneller zu debuggen als in Anwendungscode. Apidog ermöglicht es Ihnen, die MoonPay OpenAPI-Spezifikation zu importieren, Ihre Sandbox-Schlüssel als Umgebungsvariablen zu speichern und den gesamten Zyklus von Kaufangebot, Transaktionsstatus und Webhook-Wiederholung auszuführen, ohne Ihr Backend zu berühren.

Ein praktischer Workflow: Erstellen Sie eine Apidog-Umgebung für sandbox und eine weitere für production, skripten Sie die Signaturerzeugung als Pre-Request-Hook mit dem obigen Node-Krypto-Snippet und speichern Sie Beispiel-Transaktions-IDs als Variablen, damit Sie direkt von createTransaction zu getTransactionStatus springen können. Wenn ein Webhook in Produktion ankommt, kopieren Sie den Rohkörper in Apidogs Mock-Server und spielen Sie ihn gegen Ihren lokalen Endpunkt ab, bis Ihr Verifizierer bestanden hat. Laden Sie Apidog herunter, um die Signier-Hooks, den Mock-Server und den Umgebungswechsler an einem Ort zu erhalten.

FAQ

Brauche ich zusätzlich zu MoonPay meinen eigenen KYC-Anbieter?Nein. MoonPay führt die Identitätsprüfung serverseitig durch; Ihre App sieht niemals ein ID-Dokument. Wenn Sie die Verifizierung für andere Teile Ihres Produkts vorladen möchten, siehe unseren Vergleich der besten KYC-APIs.

Kann ich MoonPay verwenden, ohne deren Marken-Widget anzuzeigen?Ja, über die direkte API oder das Headless Ramps SDK, aber Sie benötigen eine zusätzliche Compliance-Prüfung, da der Marken-Flow viele der erforderlichen Offenlegungen automatisch abdeckt. Die meisten Teams implementieren zuerst das Widget und migrieren, sobald das Volumen die Prüfung rechtfertigt.

Welche Länder unterstützt MoonPay?Über 160 Länder für den Kauf und eine kleinere Anzahl (etwa 50) für den Verkauf, wobei die Verfügbarkeit von Währungen und Zahlungsmethoden je nach Region variiert. Der Currencies-Endpunkt gibt die aktuelle Matrix pro Benutzerstandort zurück.

Wie lange dauert eine Transaktion?Kartenkäufe werden im Idealfall innerhalb von fünf Minuten auf die Wallet des Benutzers übertragen. Banküberweisungen benötigen 1-3 Werktage für die Fiat-Clearing, bevor Krypto freigegeben wird. Verkaufs-Transaktionen überweisen Fiat innerhalb von 1-3 Tagen nach den On-Chain-Bestätigungen auf das Bankkonto des Benutzers.

Was passiert, wenn eine Webhook-Zustellung fehlschlägt?MoonPay versucht es mit exponentiellem Backoff bis zu 24 Stunden lang erneut. Sie sollten eine 2xx-Antwort nur zurückgeben, nachdem Sie das Ereignis gespeichert haben, und Duplikate anhand der id deduplizieren, da Wiederholungsversuche Duplikate erzeugen können.

Ist die Sandbox produktionsäquivalent?Nahezu, aber nicht identisch. Geo-Beschränkungen sind gelockert, KYC wird mit Testdokumenten umgangen und Transaktionen durchlaufen Zustände basierend auf Dashboard-Kontrollen. Führen Sie immer einen abschließenden Produktions-Smoke-Test durch, nachdem die Schlüssel ausgestellt wurden.