Como Usar a API MoonPay: Integração Fiat On-Ramp e Off-Ramp

Os on-ramps de fiat para cripto costumavam envolver semanas de papelada, integração bancária e fornecedores de KYC. Com a API da MoonPay, todo esse fluxo é simplificado: basta gerar uma URL assinada, inserir um widget no seu app e a MoonPay cuida do processamento de cartões, transferências, KYC e liquidação na carteira do usuário.

Experimente o Apidog hoje

Este guia mostra, passo a passo, como integrar a API da MoonPay: desde a criação da conta de parceiro, diferenças entre widget e API direta, geração de URL assinada, validação de webhooks, fluxo de venda (off-ramp), checkout de NFT e limites de conformidade. Todos os exemplos foram testados no sandbox e documentados no portal oficial de desenvolvedores da MoonPay. Você pode executar todas as chamadas no Apidog enquanto desenvolve.

Se está comparando fornecedores, confira nosso resumo das melhores APIs de on-ramp e off-ramp de fiat para ver como a MoonPay se compara a Transak, Ramp e Stripe Crypto. Se avalia infraestrutura de custódia, veja também como usar a API da Circle para entender o lado USDC da stack.

RESUMO

• MoonPay é uma plataforma regulamentada de on/off-ramp fiat↔cripto, usada por carteiras, marketplaces de NFT e exchanges em +160 países.
• Duas formas de integração: SDK/widget Ramps (rápido, UI hospedada) ou API REST direta (controle total, UI customizada).
• Todas as URLs de widget exigem assinatura HMAC-SHA256 usando sua chave secreta; sem assinatura, a URL é rejeitada.
• KYC, processamento de cartão e trilhos bancários são feitos pela MoonPay; status é enviado via webhooks assinados (HMAC).
• Taxas: processamento (3,5%-4,5% cartão; menor para transferência) + taxa de rede, tudo exibido ao usuário.
• Off-ramp (venda): fluxo espelhado do de compra — URL assinada, usuário envia cripto, MoonPay liquida fiat para o banco.

O que é MoonPay?

MoonPay é uma empresa licenciada que permite comprar/vender criptomoedas com cartão, transferência, Apple Pay, Google Pay, SEPA e métodos locais. Opera como empresa de serviços financeiros nos EUA, tem licença EMI na UE e registros no Reino Unido, Canadá e Austrália. Resultado: você não precisa se tornar um transmissor de dinheiro para aceitar cartão e entregar cripto (ex: ETH) na carteira do usuário.

Suporte a +110 criptomoedas em +40 redes (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum) e checkout de NFT. É a on-ramp usada pela MetaMask, Trust Wallet e OpenSea.

Autenticação e configuração

1. Cadastre uma conta de parceiro em moonpay.com/business.
2. Após aprovação, você recebe dois pares de chaves: sandbox e produção.
3. Cada par: chave publicável (pk_test_...) e chave secreta (sk_test_...). Guarde a chave secreta — ela assina URLs e valida webhooks.

Defina as variáveis no seu ambiente:

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

O sandbox replica os endpoints da produção, mas retorna transações de teste que você pode manipular via dashboard. Faça todo o fluxo em sandbox e só troque para produção após aprovação de compliance.

Endpoints principais

Os endpoints mais usados são: moedas, cotações, transações e webhooks. Veja a referência REST completa.

Listar moedas suportadas

Para montar um seletor, puxe a lista de moedas. A disponibilidade varia por país, então filtre por IP ou localização do usuário.

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

O retorno traz code, name, type (crypto/fiat), minBuyAmount, maxBuyAmount e metadados por rede.

Obter cotação em tempo real

Mostre ao usuário quanto ele receberá antes de prosseguir. As taxas já estão incluídas.

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"

O retorno inclui quoteCurrencyAmount, feeAmount, networkFeeAmount e totalAmount. Faça cache por até ~60s.

Construir URL de widget de compra assinada (Node)

O jeito mais rápido: gere uma URL com parâmetros, assine com sua chave secreta e redirecione o usuário ou use em um 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)}`;
}

Passe esta URL ao usuário. A assinatura impede alteração de parâmetros críticos (ex: walletAddress). Veja todos os parâmetros suportados no guia de início rápido do widget.

Verificar assinaturas de webhook

Receba eventos (transaction_created, transaction_updated, transaction_failed, etc) no seu endpoint. Cada requisição traz o header Moonpay-Signature-V2; valide antes de confiar.

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

Rejeite requisições com timestamp acima de 5 minutos (protege contra replay). Veja todos os eventos e formatos na referência de webhook.

Fluxo de Venda (off-ramp)

O fluxo de venda é semelhante ao de compra: gere uma URL assinada para sell.moonpay.com, usuário escolhe moeda e valor, MoonPay gera endereço de depósito, usuário envia cripto, MoonPay liquida fiat na conta bancária.

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()}`;
// assine do mesmo jeito que a URL de compra

O parâmetro refundWalletAddress é obrigatório para reembolso em caso de erro ou envio incorreto de ativo.

Checkout de NFT

Permite que o usuário compre um NFT listado usando cartão. Registre a listagem na MoonPay (ou usando uma integração de marketplace suportada), então gere uma URL assinada com contractAddress, tokenId e listingId. A MoonPay processa fiat e transferência on-chain em um único fluxo — útil para vendas primárias de alto valor.

Erros comuns e limites de taxa

• 400 invalid_signature: Assinatura não bate. Verifique se assinou exatamente a string de consulta enviada.
• 403 geo_restricted: IP do usuário em país não suportado. Verifique isAllowed no objeto moeda.
• 422 transaction_limit_exceeded: Limite diário/semanal/mensal excedido. Limite padrão cartão: $2.000/dia, $10.000/mês até KYC avançado.
• 429 rate_limited: Cerca de 100 req/min por API key em endpoints públicos. Faça cache agressivo de moedas e cotações.

Confie no webhook para status. Se o usuário fechar a aba, a carteira será financiada quando o evento transaction_updated chegar com status: completed.

Se oferece multi-carteira, consulte como usar a API da MetaMask e as melhores APIs de carteira. Para identidade/KYC, veja o nosso resumo das melhores APIs de KYC.

Preços da MoonPay

Taxas cobradas e exibidas ao usuário no widget:

• Cartão: 3,5%-4,5% do valor fiat (mínimo $3,99).
• Transferência bancária (ACH, SEPA, Open Banking): 1%-1,9%, ideal para grandes volumes.
• Taxa de rede: repassada conforme custo (depende da blockchain).
• Venda (off-ramp): estrutura similar, taxas de pagamento conforme sistema de destino.

Revenue share para parceiros é negociável. Grandes integrações têm preços e compliance dedicados.

Testando MoonPay com Apidog

Assinaturas de URLs e webhooks são os maiores pontos de falha. Use o Apidog para importar a OpenAPI da MoonPay, armazenar chaves do sandbox como variáveis e rodar o ciclo completo de cotação, status de transação e replay de webhook — sem mexer no backend.

Fluxo recomendado: crie ambientes Apidog para sandbox e production, use o snippet Node crypto para gerar assinaturas como hook de pré-requisição, salve IDs de transações como variáveis para alternar rapidamente entre createTransaction e getTransactionStatus. Ao receber um webhook em produção, copie o corpo bruto para o mock server do Apidog e teste contra seu endpoint local até validar o verificador. Baixe o Apidog para usar hooks de assinatura, mock server e alternância de ambiente em um só lugar.

FAQ

Preciso de fornecedor de KYC além da MoonPay? Não. A MoonPay faz o KYC no servidor; seu app não vê documentos de identidade. Se quiser antecipar a verificação, veja nosso comparativo das melhores APIs de KYC.

Posso usar MoonPay sem o widget deles? Sim, via API direta ou SDK Ramps headless, mas exige revisão extra de compliance, pois o fluxo de marca cobre várias obrigações legais. Recomenda-se lançar com widget e migrar para headless quando o volume justificar.

Quais países são suportados? Mais de 160 para compra, cerca de 50 para venda. Moeda e método de pagamento variam por região. O endpoint de moedas retorna a matriz atual por localização.

Quanto tempo leva uma transação? Cartão: cripto liberada em até 5 minutos. Transferência bancária: 1-3 dias úteis para liquidação. Venda: fiat na conta em 1-3 dias após confirmações on-chain.

O que acontece se um webhook falhar? MoonPay tenta novamente com backoff exponencial por até 24h. Retorne 2xx só após persistir o evento. Deduplica via id — retries podem gerar duplicatas.

Sandbox é igual à produção? Próximo, mas não idêntico. Restrições geográficas relaxadas, KYC simulado com docs de teste e transações com controle manual. Faça sempre um teste final em produção após as chaves serem emitidas.