Cómo usar la API de MoonPay: Integración Fiat On-Ramp y Off-Ramp

Las pasarelas de entrada de fiat a cripto solían requerir semanas de papeleo, relaciones bancarias y una combinación manual de proveedores de KYC. Con la API de MoonPay, todo ese proceso se reduce a una sola integración: generas una URL firmada, insertas un widget en tu app, y MoonPay gestiona el procesamiento de tarjetas, transferencias, verificación de identidad y pagos a la wallet del usuario.

Prueba Apidog hoy

Esta guía cubre paso a paso cómo usar la API de MoonPay: configuración de la cuenta, diferencias entre widget y API directa, construcción de URLs firmadas, verificación de webhooks, flujo de venta, checkout de NFT y consideraciones de compliance. Todas las solicitudes aquí mostradas fueron testeadas en sandbox y documentadas en el portal oficial para desarrolladores de MoonPay. Puedes ejecutar las mismas llamadas con Apidog durante tu integración.

Si estás comparando opciones, revisa este resumen de las mejores APIs de entrada y salida de fiat para comparar MoonPay con Transak, Ramp y Stripe Crypto. Si evalúas infraestructura de custodia, consulta cómo usar la API de Circle para ver la integración del lado USDC.

En resumen

• MoonPay es una rampa de entrada y salida fiat-cripto regulada, usada por wallets, marketplaces NFT e intercambios en 160+ países.
• Dos formas de integrar: el SDK/widget de Ramps (rápido, UI alojada por MoonPay) o la API REST directa (más control, UI propia).
• Todas las URLs del widget deben firmarse con HMAC-SHA256 usando tu clave secreta; las URLs sin firmar serán rechazadas en producción.
• MoonPay maneja KYC, procesamiento de tarjetas y transferencias bancarias en backend; recibes el estado via webhooks firmados HMAC.
• Precios: comisión de procesamiento (3.5%-4.5% en tarjeta, menos en transferencia) más la comisión de red, todo transparente al usuario.
• El flujo de venta (off-ramp) es simétrico al de compra: URL firmada, usuario envía cripto a una dirección, MoonPay liquida fiat al banco.

¿Qué es MoonPay?

MoonPay es una fintech de pagos con licencia que permite a tus usuarios comprar y vender cripto usando tarjetas, transferencias, Apple Pay, Google Pay, SEPA y métodos locales. Opera como MSB en EE. UU., tiene licencia EMI en la UE y registros en Reino Unido, Canadá y Australia. Así, no necesitas convertirte en transmisor de dinero para aceptar una tarjeta y entregar cripto al usuario.

MoonPay soporta 110+ criptos sobre 40+ redes (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), incluyendo pagos NFT. Es el on-ramp usado en MetaMask, Trust Wallet y OpenSea.

Autenticación y configuración

1. Regístrate en moonpay.com/business. Una vez aprobado, tendrás dos sets de claves: sandbox y producción, cada uno con una clave publicable (pk_test_...) y una secreta (sk_test_...). La secreta debe tratarse como contraseña: úsala para firmar URLs y verificar webhooks.

2. Configura las variables de entorno:
   

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

El sandbox replica los endpoints de producción pero simula transacciones. Úsalo para pruebas completas y cambia a las claves live tras aprobación de compliance.

Endpoints principales

MoonPay expone endpoints clave para monedas, cotizaciones, transacciones y webhooks. Consulta la referencia REST para recursos completos.

Listar monedas soportadas

Recupera la lista de monedas en vivo. Filtra resultados según IP o país del usuario:

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

La respuesta incluye code, name, type (crypto o fiat), minBuyAmount, maxBuyAmount y metadatos por red.

Obtener cotización en tiempo real

Muestra al usuario la cantidad exacta de cripto antes de continuar, con tarifas incluidas:

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"

Recibirás quoteCurrencyAmount, feeAmount, networkFeeAmount y totalAmount. La cotización es válida por ~60 segundos.

Construir una URL firmada para el widget de compra (Node)

El widget es la forma más rápida de integrar. Construye una URL con parámetros, fírmala y redirige al usuario o embébela en un 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)}`;
}

Entrega esta URL al usuario. La firma vincula los parámetros a tu cuenta, evitando manipulación. Consulta la guía oficial para más parámetros.

Verificar firmas de webhook

MoonPay notifica eventos (transaction_created, transaction_updated, transaction_failed, etc.) a tu endpoint. Verifica siempre la cabecera Moonpay-Signature-V2:

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

Rechaza solicitudes de más de 5 minutos para evitar replays. Consulta la referencia de webhooks para eventos y payloads.

Flujo de venta (off-ramp)

Genera una URL firmada apuntando a sell.moonpay.com. El usuario selecciona cripto y monto, MoonPay genera la dirección de depósito y, tras la confirmación on-chain, liquida el fiat:

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()}`;
// firmar igual que la URL de compra

refundWalletAddress es clave: si hay error o KYC fallido, MoonPay reembolsa ahí.

Pago de NFT

Permite a un usuario comprar un NFT listado con tarjeta. Registra la publicación con MoonPay o usa integración soportada, genera una URL firmada con contractAddress, tokenId y listingId. MoonPay gestiona fiat y transferencia on-chain en un solo flujo.

Errores comunes y límites de tasa

Problemas típicos:

• 400 invalid_signature: la entrada HMAC no coincide. Asegúrate de firmar exactamente la cadena de consulta enviada.
• 403 geo_restricted: IP del usuario en país no soportado. Verifica isAllowed en el objeto moneda antes de mostrarla.
• 422 transaction_limit_exceeded: el usuario superó límites diarios/semanales/mensuales. Los límites suelen ser $2,000/día y $10,000/mes hasta completar KYC avanzado.
• 429 rate_limited: supera 100 requests/minuto por API key en endpoints públicos. Cachea listados de monedas/cotizaciones.

Confía siempre en el webhook para el estado final, no en el navegador del usuario. Si cierra la pestaña antes de la redirección, la wallet igual puede estar financiada tras transaction_updated con status: completed.

Si trabajas con multi-wallets, revisa nuestras guías sobre cómo usar la API de MetaMask y las mejores APIs de billeteras cripto. Para integración de KYC, revisa las mejores APIs de KYC.

Precios de MoonPay

MoonPay cobra una comisión de procesamiento + comisión de red, ambas visibles en el widget:

• Tarjetas: 3.5%-4.5% del monto fiat, mínimo $3.99.
• Transferencia bancaria (ACH, SEPA, Open Banking): 1%-1.9%, mucho más bajo en transacciones grandes.
• Tarifa de red: traspasada al usuario, varía según blockchain y congestión.
• Off-ramp: estructura similar, con tarifas de pago según canal.

Revenue share para partners se negocia según volumen. Grandes integraciones logran precios personalizados y soporte dedicado.

Probando MoonPay con Apidog

Las URLs firmadas y los webhooks HMAC suelen ser los puntos críticos de integración. Es más eficiente depurarlos en un cliente API que desde la app. Apidog permite importar el OpenAPI de MoonPay, guardar tus claves sandbox como variables y testear el ciclo completo (cotización, estado de transacción, pruebas de webhook) sin tocar tu backend.

Flujo recomendado: crea un entorno Apidog para sandbox y otro para production, implementa el script de firma como hook de pre-solicitud (usando el snippet Node crypto), y guarda IDs de transacción como variables. Así puedes saltar de createTransaction a getTransactionStatus rápidamente. Cuando recibas un webhook en producción, copia el raw body al mock server de Apidog y reprodúcelo hasta que tu verificador pase. Descarga Apidog para acceder a hooks de firma, mock server y selector de entorno.

Preguntas frecuentes

¿Necesito mi propio proveedor de KYC además de MoonPay?

No. MoonPay hace la verificación de identidad en backend; tu app nunca ve IDs. Si necesitas KYC previo para otras partes, revisa nuestro análisis de las mejores APIs de KYC.

¿Puedo usar MoonPay sin el widget de marca?

Sí, usando la API directa o el SDK sin UI, pero requiere revisión de cumplimiento adicional, ya que el widget cubre automáticamente muchas divulgaciones regulatorias. La mayoría de los equipos lanzan primero con el widget y migran luego si el volumen lo justifica.

¿Qué países soporta MoonPay?

Más de 160 para compra, alrededor de 50 para venta. Monedas y métodos varían por región. El endpoint de monedas muestra la matriz actual según ubicación.

¿Cuánto tarda una transacción?

Compra con tarjeta: menos de 5 minutos en condiciones ideales. Transferencias bancarias: 1-3 días hábiles para liquidación fiat antes de entregar cripto. Ventas: fiat al banco en 1-3 días tras confirmación on-chain.

¿Qué pasa si falla un webhook?

MoonPay reintenta con backoff exponencial por hasta 24h. Solo responde 2xx tras persistir el evento; elimina duplicados por id.

¿El sandbox es idéntico a producción?

Casi, pero no del todo. Las restricciones geográficas son más laxas, el KYC se omite con documentos de prueba y las transacciones cambian de estado desde el panel. Haz siempre un test final en producción tras recibir tus claves.