Antoine Laurent

Posted on Apr 23 • Originally published at apidog.com

Comment utiliser l'API MoonPay : Intégration On-Ramp et Off-Ramp Fiat

Les rampes d'accès fiat-vers-crypto impliquaient autrefois des semaines de gestion bancaire, de conformité et d'intégration KYC. L'API MoonPay simplifie ce processus : vous générez une URL signée, intégrez un widget dans votre application, et MoonPay s'occupe du paiement, du KYC, et du transfert de crypto vers le portefeuille de l'utilisateur.

Essayez Apidog dès aujourd'hui

Ce guide détaille l'intégration complète de l'API MoonPay : configuration du compte partenaire, choix entre widget ou API directe, génération d'URL signées, gestion des webhooks, flux d'achat/vente, paiement NFT et points de conformité. Tous les exemples ci-dessous sont testés sur le bac à sable et documentés dans le portail développeur officiel de MoonPay. Vous pouvez exécuter les mêmes appels dans Apidog pendant le développement.

Si vous comparez encore les solutions, commencez par notre comparatif des meilleures API de rampe d'accès et de sortie fiat pour situer MoonPay face à Transak, Ramp et Stripe Crypto. Les développeurs qui évaluent l'infrastructure de garde peuvent également lire comment utiliser l'API Circle pour l'intégration USDC.

TL;DR

MoonPay est une rampe d'accès/sortie fiat-crypto réglementée, utilisée par des portefeuilles, marchés NFT et exchanges dans 160+ pays.
Deux options d'intégration : SDK/widget Ramps (rapide, UI hébergée) ou API REST directe (contrôle complet, UI custom).
Toutes les URLs de widget doivent être signées en HMAC-SHA256 avec la clé secrète ; les URL non signées sont refusées.
KYC, paiement et rails bancaires sont gérés côté serveur via MoonPay ; statut reçu via webhooks signés HMAC.
Tarification : frais de traitement (3,5–4,5 % pour carte, moins pour virement) + frais réseau, refacturés à l'utilisateur.
Le process de sortie (vente) est symétrique à l'achat : URL signée, utilisateur envoie la crypto, MoonPay crédite le compte bancaire.

Qu'est-ce que MoonPay ?

MoonPay est un prestataire de paiement agréé permettant à vos utilisateurs d’acheter/vendre des cryptos via carte, virement, Apple Pay, Google Pay, SEPA et autres systèmes locaux. Il est entreprise de services monétaires aux US, possède une licence EMI en UE, et est enregistré au UK, Canada, Australie. Résultat : pas besoin de devenir émetteur de monnaie pour accepter des paiements et livrer de la crypto.

La plateforme supporte 110+ cryptos sur 40+ réseaux (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), et le paiement NFT. Utilisée par MetaMask, Trust Wallet, OpenSea, etc.

Authentification et configuration

Inscrivez-vous sur moonpay.com/business. Après validation, vous obtenez deux paires de clés : sandbox et production. Chaque paire inclut une clé publiable (pk_test_...) et une clé secrète (sk_test_...). Protégez la clé secrète : elle signe les URLs et vérifie les webhooks.

Définissez-les dans votre environnement :

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

Le bac à sable reprend les mêmes endpoints que la production, mais retourne des transactions de test pilotables via le dashboard. Utilisez-le pour tester le parcours complet avant de passer en production après validation de conformité.

Points d'accès principaux

Les endpoints principaux : devises, cotations, transactions, webhooks. La référence REST complète liste toutes les ressources.

Lister les devises supportées

Pour construire un sélecteur dynamique, récupérez la liste live. La disponibilité dépend du pays, filtrez donc selon l'IP ou le lieu utilisateur.

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

La réponse contient code, name, type (crypto/fiat), minBuyAmount, maxBuyAmount et les métadonnées réseau.

Obtenir une cotation en temps réel

Affichez à l'utilisateur le montant exact de crypto avant l'achat (frais inclus).

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"

Vous recevez : quoteCurrencyAmount, feeAmount, networkFeeAmount, totalAmount. Mettez en cache la cotation pendant ~60s.

Générer une URL de widget d'achat signée (Node)

Le widget est la voie la plus rapide pour intégrer MoonPay. Construisez l'URL avec les paramètres requis, signez-la en HMAC-SHA256, puis redirigez ou chargez en iframe.

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

Passez cette URL à l'utilisateur. La signature protège tous les paramètres. Consultez le guide rapide widget pour la liste complète des paramètres.

Vérifier les signatures de webhook

MoonPay envoie des webhooks pour chaque événement clé (transaction_created, transaction_updated, etc.). Vérifiez l'en-tête Moonpay-Signature-V2 avant d'accepter la charge utile.

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

Refusez les requêtes de plus de 5 minutes (anti-rejeu). Consultez la doc webhooks pour tous les types d'événements.

Flux de vente (off-ramp)

La vente fonctionne comme l'achat : générez une URL signée vers sell.moonpay.com, l'utilisateur choisit la crypto et le montant, MoonPay génère une adresse de dépôt, l'utilisateur envoie ses fonds. Après confirmation on-chain, MoonPay crédite le compte bancaire.

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()}`;
// Ajoutez la signature comme pour l'URL d'achat

refundWalletAddress : essentiel pour rembourser si erreur d'actif ou échec KYC.

Paiement NFT

Pour permettre l'achat de NFT par carte : enregistrez l'offre auprès de MoonPay (ou via une marketplace partenaire), puis générez une URL signée incluant contractAddress, tokenId, listingId. MoonPay gère le paiement fiat et le transfert on-chain, réduisant fortement l'abandon lors des ventes primaires.

Erreurs courantes et limites de débit

Points d'échec classiques :

400 invalid_signature : votre HMAC ne correspond pas au serveur. Vérifiez l'encodage de la chaîne signée.
403 geo_restricted : IP de l'utilisateur dans un pays non supporté. Vérifiez isAllowed sur l'objet devise.
422 transaction_limit_exceeded : plafond utilisateur atteint (2 000 $/jour, 10 000 $/mois avant KYC renforcé).
429 rate_limited : ~100 requêtes/minute par clé API sur les endpoints publics. Cachez agressivement les listes et cotations.

Fiez-vous au webhook pour l'état réel (pas au navigateur). Si l'utilisateur ferme l'onglet, le crédit portefeuille se fera quand même à la réception du webhook transaction_updated avec status: completed.

Pour le multi-wallet, consultez nos guides API MetaMask et meilleures API de portefeuille crypto. Pour le KYC, voir notre comparatif API KYC.

Tarification MoonPay

MoonPay facture un frais de traitement + frais réseau, tous affichés à l'utilisateur :

Carte : 3,5–4,5 % du montant fiat, minimum 3,99 $.
Virement (ACH, SEPA, Open Banking) : 1–1,9 %, avantageux pour gros montants.
Frais réseau : coût de la blockchain, variable selon la congestion.
Vente : structure similaire, frais selon rail de sortie.

Le partage de revenus est négocié après un certain volume. Les intégrations à fort volume bénéficient de tarifs personnalisés et d'un contact conformité dédié.

Tester MoonPay avec Apidog

Les signatures d’URL et les webhooks HMAC sont les principales sources d’erreur d’intégration. Apidog permet d’importer l’OpenAPI de MoonPay, de gérer les clés de sandbox comme variables d’environnement, et d’exécuter le cycle complet (cotations, statuts, relecture webhook) sans toucher à votre backend.

Procédure recommandée : créez un environnement Apidog pour sandbox et un autre pour production, script la génération de signature en hook de pré-requête (utilisez l'extrait Node crypto ci-dessus), stockez des IDs de transaction comme variables pour passer directement de createTransaction à getTransactionStatus. Lorsqu'un webhook arrive en production, copiez le corps brut dans le simulateur d’Apidog pour tester votre vérification de signature en local. Téléchargez Apidog pour bénéficier de tous ces outils en un seul endroit.

FAQ

Ai-je besoin de mon propre fournisseur KYC en plus de MoonPay ?

Non. MoonPay effectue le KYC côté serveur ; votre application ne traite jamais les documents. Si besoin d’anticiper la vérif pour d'autres usages, consultez notre comparatif API KYC.

Puis-je utiliser MoonPay sans leur widget de marque ?

Oui, via l’API directe ou le SDK sans interface, mais un audit de conformité supplémentaire est requis (le widget couvre automatiquement beaucoup d’obligations). Beaucoup d’équipes déploient d’abord le widget puis migrent.

Quels pays sont supportés ?

Plus de 160 pays pour l’achat, ~50 pour la vente. La disponibilité des devises/méthodes varie par région. L’endpoint currencies donne la matrice exacte selon la géoloc utilisateur.

Combien de temps prend une transaction ?

Carte : crédit portefeuille en moins de 5 minutes si tout va bien. Virement : 1–3 jours ouvrés pour le fiat avant la livraison crypto. Vente : fiat crédité sous 1–3 jours après confirmation on-chain.

Que se passe-t-il si la livraison d’un webhook échoue ?

MoonPay retente via backoff exponentiel pendant 24h. Répondez 2xx seulement après persistance de l'événement, et dédupliquez sur l’id (réessais possibles).

Le bac à sable est-il strictement identique à la prod ?

Presque, mais pas entièrement : restrictions géographiques allégées, KYC contourné avec des documents de test, et transactions pilotées via le dashboard. Faites toujours un test final en production après la génération des clés.

DEV Community