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

Les rampes d'accès fiat-vers-crypto signifiaient autrefois des semaines de paperasse de conformité, de relations bancaires et de fournisseurs KYC assemblés avec du ruban adhésif. L'API MoonPay condense cette pile en une seule intégration : vous générez une URL signée, insérez un widget dans votre application, et MoonPay gère le traitement des cartes, les virements bancaires, la vérification d'identité et les paiements vers le portefeuille d'un utilisateur.

Ce guide explique comment utiliser l'API MoonPay de bout en bout : configuration du compte partenaire, widget vs API directe, construction d'URL signées, vérification des webhooks, le flux de vente, le paiement NFT et les limites de conformité à prendre en compte. Chaque requête ci-dessous a été testée par rapport au bac à sable et documentée dans le portail développeur officiel de MoonPay. Vous pouvez exécuter les mêmes appels dans Apidog pendant que vous développez.

bouton

Si vous comparez toujours des fournisseurs, commencez par notre tour d'horizon des meilleures API de rampe d'accès et de sortie fiat pour voir où MoonPay se positionne par rapport à Transak, Ramp et Stripe Crypto. Les développeurs évaluant l'infrastructure de garde devraient également lire comment utiliser l'API Circle pour une vue du côté USDC de la pile.

TL;DR

MoonPay est une rampe d'accès et de sortie fiat-vers-crypto réglementée utilisée par les portefeuilles, les marchés NFT et les bourses dans plus de 160 pays.
Deux chemins d'intégration : le SDK/widget Ramps (le plus rapide, interface utilisateur hébergée par MoonPay) ou l'API REST directe (contrôle total, vous construisez l'interface utilisateur).
Toutes les URL de widget doivent être signées avec HMAC-SHA256 en utilisant votre clé secrète ; les URL non signées sont rejetées en production.
Le KYC, le traitement des cartes et les rails bancaires sont gérés côté serveur par MoonPay ; vous recevez le statut via des webhooks signés avec le même schéma HMAC.
La tarification est un frais de traitement (3,5 %-4,5 % pour les cartes, moins pour les virements bancaires) plus les frais de réseau sous-jacents, transmis de manière transparente à l'utilisateur.
Le processus de sortie (vente) reflète le processus d'achat : URL signée, l'utilisateur envoie des cryptos à une adresse de dépôt, MoonPay règle les fiat sur le compte bancaire de l'utilisateur.

Qu'est-ce que MoonPay ?

MoonPay est une société de paiement agréée qui permet à vos utilisateurs d'acheter et de vendre des cryptos avec des cartes, des virements bancaires, Apple Pay, Google Pay, SEPA et des systèmes locaux. Elle opère en tant qu'entreprise de services monétaires aux États-Unis, possède une licence EMI dans l'UE et détient des enregistrements au Royaume-Uni, au Canada et en Australie. L'effet pratique : vous n'avez pas besoin de devenir un émetteur de monnaie pour accepter une carte et livrer de l'ETH au portefeuille d'un utilisateur.

La plateforme couvre plus de 110 crypto-monnaies sur plus de 40 réseaux (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), ainsi que le paiement NFT. C'est la rampe d'accès utilisée par MetaMask, Trust Wallet et OpenSea.

Authentification et configuration

Inscrivez-vous pour un compte partenaire sur moonpay.com/business. Après approbation, vous recevrez deux ensembles de clés : un pour le bac à sable (sandbox) et un pour la production. Chaque ensemble comprend une clé publiable (pk_test_...) et une clé secrète (sk_test_...). Traitez la clé secrète comme un mot de passe de base de données ; elle signe chaque URL et vérifie chaque webhook.

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 (sandbox) a les mêmes points d'extrémité que la production mais renvoie des transactions de test que vous pouvez faire passer entre différents états à l'aide du tableau de bord. Utilisez-le pour le chemin complet "happy path", puis passez aux clés de production une fois que votre examen de conformité avec MoonPay est terminé.

Points d'accès principaux

MoonPay expose quelques groupes de points d'accès que vous utiliserez le plus souvent : devises, cotations, transactions et webhooks. La référence REST complète liste toutes les ressources.

Lister les devises prises en charge

Avant de construire un sélecteur, récupérez la liste en direct. La disponibilité varie selon les pays, vous devriez donc filtrer avec l'adresse IP de l'utilisateur ou le lieu déclaré.

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

La réponse renvoie un tableau avec code, name, type (crypto ou fiat), minBuyAmount, maxBuyAmount et des métadonnées par réseau pour les jetons qui résident sur plusieurs chaînes.

Obtenir une cotation en temps réel

Les cotations indiquent à l'utilisateur exactement combien de crypto il recevra avant de s'engager. Les frais sont 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 en retour quoteCurrencyAmount, feeAmount, networkFeeAmount et totalAmount. Mettez la cotation en cache pendant les quelques secondes que l'utilisateur met à cliquer ; MoonPay l'honore pendant environ 60 secondes.

Le widget d'achat est le chemin le plus rapide vers une intégration fonctionnelle. Vous construisez une URL avec des paramètres de requête, la signez avec votre secret, puis redirigez l'utilisateur ou la chargez dans une iframe. Voici la version Node :

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 lie les paramètres à votre compte, de sorte qu'un client malveillant ne peut pas échanger le walletAddress ou modifier le montant sans l'invalider. Le guide de démarrage rapide du widget d'achat documente chaque paramètre pris en charge.

Vérifier les signatures de webhook

MoonPay envoie des événements de cycle de vie à votre point de terminaison : transaction_created, transaction_updated, transaction_failed, et les variantes de vente/NFT. Chaque requête inclut un en-tête Moonpay-Signature-V2 que vous devez vérifier avant de faire confiance à 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"),
  );
}

Rejetez toute requête de plus de cinq minutes pour empêcher les attaques par rejeu. La référence des webhooks liste chaque type d'événement et la forme de la charge utile.

Flux de vente (off-ramp)

Le flux de vente est similaire à l'achat. Vous construisez une URL signée pointant vers sell.moonpay.com, l'utilisateur choisit une crypto et un montant, MoonPay génère une adresse de dépôt, et l'utilisateur envoie des fonds depuis son portefeuille. Une fois la transaction confirmée sur la chaîne, MoonPay règle le fiat sur le compte bancaire lié de l'utilisateur.

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 est important : si l'utilisateur envoie le mauvais actif ou si la transaction échoue au KYC, MoonPay y renvoie les fonds.

Paiement NFT

Le paiement NFT permet à un utilisateur d'acheter un NFT listé avec une carte. Vous enregistrez l'offre auprès de MoonPay (ou utilisez une intégration de marché prise en charge), puis générez une URL signée avec contractAddress, tokenId et listingId. MoonPay gère la partie fiat et le transfert on-chain en un seul flux, ce qui réduit considérablement les abandons lors des ventes primaires de grande valeur.

Erreurs courantes et limites de débit

La plupart des problèmes d'intégration se résument à une courte liste :

400 invalid_signature signifie que votre entrée HMAC ne correspond pas à celle du serveur. La cause la plus fréquente est les différences d'encodage d'URL entre votre client et le signataire. Signez la chaîne de requête exacte que vous envoyez.
403 geo_restricted indique que l'adresse IP de l'utilisateur se trouve dans un pays que MoonPay ne dessert pas pour cette devise. Vérifiez le champ isAllowed sur l'objet devise avant de l'afficher.
422 transaction_limit_exceeded signifie que l'utilisateur a atteint les plafonds quotidiens, hebdomadaires ou mensuels. Les limites de carte sont généralement de 2 000 $/jour et 10 000 $/mois jusqu'à ce que l'utilisateur effectue un KYC amélioré.
429 rate_limited se déclenche à environ 100 requêtes par minute et par clé API sur les points de terminaison publics. Mettez agressivement en cache les listes de devises et les cotations.

Pour l'état, faites confiance au webhook, pas au navigateur de l'utilisateur. Un utilisateur qui ferme l'onglet avant la redirection aura toujours un portefeuille crédité une fois que l'événement transaction_updated se déclenchera avec status: completed.

Si vous développez un support multi-portefeuilles, nos guides sur comment utiliser l'API MetaMask et les meilleures API de portefeuille crypto se marient bien avec celui-ci. Pour le côté identité de la conformité, consultez notre tour d'horizon de la meilleure API KYC.

Tarification MoonPay

MoonPay facture des frais de traitement plus les frais de réseau, tous deux affichés à l'utilisateur dans le widget :

Achats par carte : 3,5 % à 4,5 % du montant fiat, avec un minimum de 3,99 $.
Virement bancaire (ACH, SEPA, Open Banking) : 1 % à 1,9 %, beaucoup moins cher pour les montants importants.
Frais de réseau : répercutés au coût, varient selon la chaîne et la congestion.
Flux de vente : structure similaire, avec des frais de paiement dépendant du rail de destination.

Le partage des revenus pour les partenaires est négocié séparément une fois que le volume augmente. Les intégrations à volume élevé bénéficient généralement d'une tarification personnalisée et d'un contact de conformité dédié.

Tester MoonPay avec Apidog

Les URL signées et les webhooks HMAC sont les deux points où la plupart des intégrations MoonPay échouent, et les deux sont plus rapides à déboguer dans un client API approprié que dans le code de l'application. Apidog vous permet d'importer la spécification OpenAPI de MoonPay, de stocker vos clés de sandbox comme variables d'environnement et d'exécuter le cycle complet de cotation d'achat, de statut de transaction et de relecture de webhook sans toucher votre backend.

Un flux de travail pratique : créez un environnement Apidog pour sandbox et un autre pour production, script la génération de signature en tant que hook de pré-requête en utilisant l'extrait de code Node crypto ci-dessus, et enregistrez des ID de transaction d'échantillon comme variables afin de pouvoir passer directement de createTransaction à getTransactionStatus. Lorsqu'un webhook arrive en production, copiez le corps brut dans le serveur de simulation d'Apidog et rejouez-le sur votre point de terminaison local jusqu'à ce que votre vérificateur passe. Téléchargez Apidog pour obtenir les hooks de signature, le serveur de simulation et le commutateur d'environnement en un seul endroit.

FAQ

Ai-je besoin de mon propre fournisseur KYC en plus de MoonPay ?Non. MoonPay effectue la vérification d'identité côté serveur ; votre application ne voit jamais de document d'identité. Si vous souhaitez anticiper la vérification pour d'autres parties de votre produit, consultez notre comparaison de la meilleure API KYC.

Puis-je utiliser MoonPay sans afficher leur widget de marque ?Oui, via l'API directe ou le SDK Ramps sans interface, mais vous aurez besoin d'un examen de conformité supplémentaire car le flux de marque couvre automatiquement de nombreuses divulgations requises. La plupart des équipes déploient d'abord le widget et migrent une fois que le volume justifie l'examen.

Quels pays MoonPay prend-il en charge ?Plus de 160 pays pour l'achat et un ensemble plus restreint (environ 50) pour la vente, avec la disponibilité des devises et des méthodes de paiement variant selon la région. Le point d'accès "currencies" renvoie la matrice actuelle par emplacement d'utilisateur.

Combien de temps prend une transaction ?Les achats par carte sont réglés sur le portefeuille de l'utilisateur en moins de cinq minutes dans le cas optimal. Les virements bancaires prennent 1 à 3 jours ouvrables pour le dédouanement du fiat avant que la crypto ne soit libérée. Les transactions de vente règlent le fiat sur la banque de l'utilisateur en 1 à 3 jours après les confirmations on-chain.

Que se passe-t-il si la livraison d'un webhook échoue ?MoonPay réessaie avec une rétention exponentielle pendant jusqu'à 24 heures. Vous devez renvoyer une réponse 2xx uniquement après avoir persévéré l'événement, et dédupliquer sur id car les réessais peuvent produire des doublons.

Le bac à sable est-il équivalent à la production ?Presque, mais pas identique. Les restrictions géographiques sont assouplies, le KYC est contourné avec des documents de test, et les transactions passent par des états basés sur les contrôles du tableau de bord. Exécutez toujours un test de fumée final en production après l'émission des clés.