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 significar semanas de papeleo de cumplimiento, relaciones bancarias y proveedores de KYC unidos con cinta adhesiva. La API de MoonPay colapsa esa pila en una sola integración: generas una URL firmada, insertas un widget en tu aplicación, y MoonPay se encarga del procesamiento de tarjetas, transferencias bancarias, verificación de identidad y pagos a la billetera de un usuario.

Esta guía explica cómo usar la API de MoonPay de principio a fin: configuración de la cuenta de socio, widget vs. API directa, construcción de URL firmada, verificación de webhook, el flujo de venta, el checkout de NFT y los límites de cumplimiento que debes tener en cuenta. Cada solicitud a continuación fue probada en el sandbox y documentada en el portal oficial para desarrolladores de MoonPay. Puedes ejecutar las mismas llamadas dentro de Apidog mientras construyes.

Si aún estás comparando proveedores, comienza con nuestro resumen de las mejores APIs de entrada y salida de fiat para ver dónde encaja MoonPay frente a Transak, Ramp y Stripe Crypto. Los desarrolladores que evalúen la infraestructura de custodia también deberían leer cómo usar la API de Circle para una visión del lado USDC de la pila.

En resumen

• MoonPay es una pasarela de entrada y salida de fiat a cripto regulada, utilizada por billeteras, mercados NFT e intercambios en más de 160 países.
• Dos rutas de integración: el SDK/widget de Ramps (el más rápido, UI alojada por MoonPay) o la API REST directa (control total, tú construyes la UI).
• Todas las URLs del widget deben ser firmadas con HMAC-SHA256 usando tu clave secreta; las URLs sin firmar son rechazadas en producción.
• KYC, procesamiento de tarjetas y vías bancarias son gestionados por MoonPay en el lado del servidor; recibes el estado a través de webhooks firmados con el mismo patrón HMAC.
• El precio es una tarifa de procesamiento (3.5%-4.5% para tarjeta, menor para transferencia bancaria) más la tarifa de red subyacente, transferida transparentemente al usuario.
• El flujo de salida (venta) refleja el flujo de compra: URL firmada, el usuario envía cripto a una dirección de depósito, MoonPay liquida el fiat al banco del usuario.

¿Qué es MoonPay?

MoonPay es una empresa de pagos con licencia que permite a tus usuarios comprar y vender cripto con tarjetas, transferencias bancarias, Apple Pay, Google Pay, SEPA y vías locales. Opera como un negocio de servicios monetarios en EE. UU., tiene una licencia EMI en la UE y posee registros en el Reino Unido, Canadá y Australia. El efecto práctico: no tienes que convertirte en un transmisor de dinero para aceptar una tarjeta y entregar ETH a la billetera de un usuario.

La plataforma cubre más de 110 criptomonedas en más de 40 redes (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), además de la opción de pago de NFT. Es la pasarela de entrada dentro de MetaMask, Trust Wallet y OpenSea.

Autenticación y configuración

Regístrate para una cuenta de socio en moonpay.com/business. Después de la aprobación, obtendrás dos conjuntos de claves: sandbox y producción. Cada conjunto tiene una clave publicable (pk_test_...) y una clave secreta (sk_test_...). Trata la clave secreta como una contraseña de base de datos; firma cada URL y verifica cada webhook.

Establécelas en tu 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 tiene los mismos endpoints que producción pero devuelve transacciones de prueba que puedes alternar entre estados usando el panel de control. Úsalo para la ruta feliz completa, luego cambia a las claves de producción una vez que tu revisión de cumplimiento con MoonPay sea aprobada.

Endpoints principales

MoonPay expone algunos grupos de endpoints que utilizarás con mayor frecuencia: monedas, cotizaciones, transacciones y webhooks. La referencia REST completa enumera todos los recursos.

Listar monedas soportadas

Antes de construir un selector, recupera la lista en vivo. La disponibilidad varía según el país, por lo que debes filtrar con la IP del usuario o la ubicación declarada.

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

La respuesta devuelve un array con code, name, type (crypto o fiat), minBuyAmount, maxBuyAmount, y metadatos por red para tokens que residen en múltiples cadenas.

Obtener una cotización en tiempo real

Las cotizaciones le dicen al usuario exactamente cuánto cripto recibirá antes de comprometerse. Las tarifas están 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. Almacena en caché la cotización durante los pocos segundos que tarda el usuario en hacer clic; MoonPay la respeta durante aproximadamente 60 segundos.

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

El widget de compra es la ruta más rápida para una integración funcional. Construyes una URL con parámetros de consulta, la firmas con tu secreto y rediriges al usuario o la cargas en un iframe. Aquí está la versión de 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)}`;
}

Pasa esta URL al usuario. La firma vincula los parámetros a tu cuenta, por lo que un cliente malicioso no puede intercambiar la walletAddress ni cambiar el monto sin invalidarla. La guía de inicio rápido del widget de compra documenta cada parámetro soportado.

Verificar firmas de webhook

MoonPay envía eventos de ciclo de vida a tu endpoint: transaction_created, transaction_updated, transaction_failed, y variantes de venta/NFT. Cada solicitud incluye un encabezado Moonpay-Signature-V2 que debes verificar antes de confiar en la carga útil.

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 cualquier solicitud de más de cinco minutos para detener ataques de repetición. La referencia de webhooks enumera cada tipo de evento y forma de carga útil.

Flujo de venta (off-ramp)

El flujo de venta refleja el de compra. Construyes una URL firmada que apunta a sell.moonpay.com, el usuario elige una cripto y un monto, MoonPay genera una dirección de depósito y el usuario envía fondos desde su billetera. Una vez que la transacción se confirma en la cadena, MoonPay liquida el fiat en la cuenta bancaria vinculada del usuario.

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 es importante: si el usuario envía el activo incorrecto o la transacción falla el KYC, MoonPay devuelve los fondos allí.

Pago de NFT

El pago de NFT permite a un usuario comprar un NFT listado con una tarjeta. Registras la publicación con MoonPay (o utilizas una integración de mercado soportada), luego generas una URL firmada con contractAddress, tokenId y listingId. MoonPay maneja la parte fiduciaria y la transferencia en cadena en un solo flujo, lo que reduce drásticamente la tasa de abandono en ventas primarias de alto valor.

Errores comunes y límites de tasa

La mayoría de los problemas de integración se encuentran en una breve lista:

• 400 invalid_signature significa que tu entrada HMAC no coincide con la del servidor. La causa más frecuente son las diferencias de codificación de URL entre tu cliente y el firmante. Firma la cadena de consulta exacta que envías.
• 403 geo_restricted indica que la IP del usuario se encuentra en un país al que MoonPay no presta servicio para esa moneda. Verifica el campo isAllowed en el objeto de la moneda antes de renderizarla.
• 422 transaction_limit_exceeded significa que el usuario alcanzó los límites diarios, semanales o mensuales. Los límites de tarjeta son típicamente $2,000/día y $10,000/mes hasta que el usuario complete un KYC mejorado.
• 429 rate_limited se activa aproximadamente a 100 solicitudes por minuto por clave API en los endpoints públicos. Almacena en caché las listas de monedas y las cotizaciones de forma agresiva.

Para el estado, confía en el webhook, no en el navegador del usuario. Un usuario que cierra la pestaña antes de la redirección aún tiene una billetera financiada una vez que el evento transaction_updated se dispara con status: completed.

Si estás construyendo soporte multi-billetera, nuestras guías sobre cómo usar la API de MetaMask y las mejores APIs de billeteras cripto combinan bien con esta. Para el lado de la identidad del cumplimiento, consulta nuestro resumen de las mejores APIs de KYC.

Precios de MoonPay

MoonPay cobra una tarifa de procesamiento más la tarifa de red, ambas mostradas al usuario dentro del widget:

• Compras con tarjeta: 3.5%-4.5% del monto fiat, con un mínimo de $3.99.
• Transferencia bancaria (ACH, SEPA, Open Banking): 1%-1.9%, mucho más barata en transacciones grandes.
• Tarifa de red: se traspasa al costo, varía según la cadena y la congestión.
• Flujo de venta: estructura similar, con tarifas de pago que dependen de la vía de destino.

La participación en los ingresos para los socios se negocia por separado una vez que el volumen aumenta. Las integraciones de alto volumen suelen obtener precios personalizados además de un contacto de cumplimiento dedicado.

Probando MoonPay con Apidog

Las URLs firmadas y los webhooks HMAC son los dos puntos donde la mayoría de las integraciones de MoonPay fallan, y ambos son más rápidos de depurar en un cliente API adecuado que en el código de la aplicación. Apidog te permite importar la especificación OpenAPI de MoonPay, almacenar tus claves de sandbox como variables de entorno y ejecutar el ciclo completo de cotización de compra, estado de transacción y reproducción de webhook sin tocar tu backend.

Un flujo de trabajo práctico: crea un entorno Apidog para sandbox y otro para production, escribe el script de generación de firma como un hook de pre-solicitud usando el fragmento de Node crypto anterior, y guarda IDs de transacciones de ejemplo como variables para que puedas saltar directamente de createTransaction a getTransactionStatus. Cuando un webhook llega a producción, copia el cuerpo raw en el servidor mock de Apidog y reprodúcelo contra tu endpoint local hasta que tu verificador pase. Descarga Apidog para obtener los hooks de firma, el servidor mock y el selector de entorno en un solo lugar.

Preguntas frecuentes

¿Necesito mi propio proveedor de KYC además de MoonPay?No. MoonPay realiza la verificación de identidad en el lado del servidor; tu aplicación nunca ve un documento de identificación. Si deseas precargar la verificación para otras partes de tu producto, consulta nuestra comparación de las mejores APIs de KYC.

¿Puedo usar MoonPay sin mostrar su widget de marca?Sí, a través de la API directa o el SDK de Ramps sin interfaz, pero necesitas una revisión de cumplimiento adicional porque el flujo de marca cubre muchas de las divulgaciones requeridas automáticamente. La mayoría de los equipos implementan el widget primero y migran una vez que el volumen justifica la revisión.

¿Qué países soporta MoonPay?Más de 160 países para compra y un conjunto más pequeño (aproximadamente 50) para venta, con la disponibilidad de monedas y métodos de pago variando según la región. El endpoint de monedas devuelve la matriz actual por ubicación del usuario.

¿Cuánto tiempo tarda una transacción?Las compras con tarjeta se liquidan en la billetera del usuario en menos de cinco minutos en el caso ideal. Las transferencias bancarias tardan de 1 a 3 días hábiles para la compensación de fiat antes de que se libere la criptomoneda. Las transacciones de venta liquidan el fiat al banco del usuario en 1-3 días después de las confirmaciones en cadena.

¿Qué sucede si falla la entrega de un webhook?MoonPay reintenta con retroceso exponencial durante hasta 24 horas. Debes devolver una respuesta 2xx solo después de haber persistido el evento, y eliminar duplicados por id porque los reintentos pueden producir duplicados.

¿Es el sandbox equivalente a producción?Cercano, pero no idéntico. Las restricciones geográficas son más flexibles, el KYC se omite con documentos de prueba y las transacciones pasan por estados basados en controles del panel. Siempre ejecuta una prueba de humo de producción final después de que se emitan las claves.