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

Os on-ramps de fiat para cripto costumavam significar semanas de papelada de conformidade, relacionamentos bancários e fornecedores de KYC unidos com fita adesiva. A API da MoonPay condensa tudo isso em uma única integração: você gera uma URL assinada, insere um widget em seu aplicativo, e a MoonPay cuida do processamento de cartões, transferências bancárias, verificação de identidade e pagamentos para a carteira de um usuário.

Este guia detalha como usar a API da MoonPay de ponta a ponta: configuração de conta de parceiro, widget vs. API direta, construção de URL assinada, verificação de webhook, fluxo de venda, checkout de NFT e os limites de conformidade que você precisa considerar. Cada solicitação abaixo foi testada no sandbox e documentada no portal oficial de desenvolvedores da MoonPay. Você pode executar as mesmas chamadas dentro do Apidog enquanto constrói.

botão

Se você ainda está comparando fornecedores, comece com nosso resumo das melhores APIs de on-ramp e off-ramp de fiat para ver onde a MoonPay se encaixa em relação a Transak, Ramp e Stripe Crypto. Desenvolvedores avaliando infraestrutura de custódia também devem ler como usar a API da Circle para ter uma visão do lado USDC da pilha.

RESUMO

MoonPay é uma plataforma regulamentada de on-ramp e off-ramp de fiat para cripto, utilizada por carteiras, marketplaces de NFT e exchanges em mais de 160 países.
Duas opções de integração: o SDK/widget Ramps (mais rápido, UI hospedada pela MoonPay) ou API REST direta (controle total, você constrói a UI).
Todas as URLs de widget devem ser assinadas com HMAC-SHA256 usando sua chave secreta; URLs não assinadas são rejeitadas em produção.
KYC, processamento de cartões e trilhos bancários são gerenciados pelo lado do servidor pela MoonPay; você recebe o status via webhooks assinados com o mesmo padrão HMAC.
O preço é uma taxa de processamento (3,5%-4,5% para cartão, menor para transferência bancária) mais a taxa de rede subjacente, repassada transparentemente ao usuário.
O off-ramp (venda) espelha o fluxo de compra: URL assinada, usuário envia cripto para um endereço de depósito, MoonPay liquida o fiat para o banco do usuário.

O que é MoonPay?

MoonPay é uma empresa de pagamentos licenciada que permite aos seus usuários comprar e vender criptomoedas com cartões, transferências bancárias, Apple Pay, Google Pay, SEPA e sistemas locais. Opera como uma empresa de serviços monetários nos EUA, possui uma licença EMI na UE e detém registros no Reino Unido, Canadá e Austrália. O efeito prático: você não precisa se tornar um transmissor de dinheiro para aceitar um cartão e entregar ETH para a carteira de um usuário.

A plataforma abrange mais de 110 criptomoedas em mais de 40 redes (Ethereum, Solana, Bitcoin, Polygon, Base, Arbitrum), além de checkout de NFT. É a on-ramp utilizada dentro da MetaMask, Trust Wallet e OpenSea.

Autenticação e configuração

Cadastre-se para uma conta de parceiro em moonpay.com/business. Após a aprovação, você receberá dois conjuntos de chaves: sandbox e produção. Cada conjunto possui uma chave publicável (pk_test_...) e uma chave secreta (sk_test_...). Trate a chave secreta como uma senha de banco de dados; ela assina cada URL e verifica cada webhook.

Defina-os em 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 possui os mesmos endpoints da produção, mas retorna transações de teste que você pode alternar entre os estados usando o painel. Use-o para o fluxo completo e, em seguida, mude para as chaves de produção assim que sua revisão de conformidade com a MoonPay for aprovada.

Endpoints principais

A MoonPay expõe alguns grupos de endpoints que você usará com mais frequência: moedas, cotações, transações e webhooks. A referência completa da REST lista cada recurso.

Listar moedas suportadas

Antes de construir um seletor, obtenha a lista atual. A disponibilidade varia por país, então você deve filtrar pelo IP do usuário ou localização declarada.

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

A resposta retorna um array com code, name, type (crypto ou fiat), minBuyAmount, maxBuyAmount e metadados por rede para tokens que existem em várias cadeias.

Obter uma cotação em tempo real

As cotações informam ao usuário exatamente quanta cripto ele receberá antes de se comprometer. As taxas 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"

Você receberá quoteCurrencyAmount, feeAmount, networkFeeAmount e totalAmount. Armazene a cotação em cache pelos poucos segundos que o usuário leva para prosseguir; a MoonPay a honra por aproximadamente 60 segundos.

O widget de compra é o caminho mais rápido para uma integração funcional. Você constrói uma URL com parâmetros de consulta, assina-a com sua chave secreta e redireciona o usuário ou a carrega em um iframe. Aqui está a versão 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)}`;
}

Passe esta URL para o usuário. A assinatura vincula os parâmetros à sua conta, de modo que um cliente mal-intencionado não pode trocar o walletAddress ou alterar o valor sem invalidá-la. O guia de início rápido do widget de compra documenta todos os parâmetros suportados.

Verificar assinaturas de webhook

A MoonPay envia eventos de ciclo de vida para o seu endpoint: transaction_created, transaction_updated, transaction_failed, e variantes de venda/NFT. Cada solicitação inclui um cabeçalho Moonpay-Signature-V2 que você deve verificar antes de confiar no payload.

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 qualquer solicitação com mais de cinco minutos para interromper ataques de replay. A referência de webhook lista todos os tipos de eventos e formatos de payload.

Fluxo de Venda (off-ramp)

O fluxo de venda espelha a compra. Você constrói uma URL assinada apontando para sell.moonpay.com, o usuário escolhe uma cripto e um valor, a MoonPay gera um endereço de depósito, e o usuário envia fundos de sua carteira. Assim que a transação for confirmada na blockchain, a MoonPay liquida o fiat para a conta bancária vinculada do usuário.

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 é importante: se o usuário enviar o ativo errado ou a transação falhar no KYC, a MoonPay retorna os fundos para lá.

Checkout de NFT

O checkout de NFT permite que um usuário compre um NFT listado com um cartão. Você registra a listagem com a MoonPay (ou usa uma integração de marketplace suportada), então gera uma URL assinada com contractAddress, tokenId e listingId. A MoonPay lida com a parte fiat e a transferência on-chain em um único fluxo, o que reduz drasticamente a desistência em vendas primárias de alto valor.

Erros comuns e limites de taxa

A maioria dos problemas de integração se enquadra em uma pequena lista:

400 invalid_signature significa que sua entrada HMAC não corresponde à do servidor. A causa mais frequente são as diferenças de codificação de URL entre seu cliente e o assinador. Assine a string de consulta exata que você envia.
403 geo_restricted indica que o IP do usuário está em um país que a MoonPay não atende para aquela moeda. Verifique o campo isAllowed no objeto da moeda antes de renderizá-lo.
422 transaction_limit_exceeded significa que o usuário atingiu os limites diários, semanais ou mensais. Os limites de cartão são tipicamente $2.000/dia e $10.000/mês até que o usuário complete um KYC aprimorado.
429 rate_limited é acionado em aproximadamente 100 requisições por minuto por chave de API em endpoints públicos. Faça cache agressivamente das listas de moedas e cotações.

Para o estado, confie no webhook, não no navegador do usuário. Um usuário que fecha a aba antes do redirecionamento ainda terá uma carteira financiada assim que o evento transaction_updated for disparado com status: completed.

Se você está construindo suporte multi-carteira, nossos guias sobre como usar a API da MetaMask e as melhores APIs de carteiras de criptomoedas combinam bem com este. Para o lado da identidade na conformidade, consulte nosso resumo das melhores APIs de KYC.

Preços da MoonPay

A MoonPay cobra uma taxa de processamento mais a taxa de rede, ambas mostradas ao usuário dentro do widget:

Compras com cartão: 3,5%-4,5% do valor fiat, com um mínimo de $3,99.
Transferência bancária (ACH, SEPA, Open Banking): 1%-1,9%, muito mais barato para grandes volumes.
Taxa de rede: repassada pelo custo, varia de acordo com a cadeia e o congestionamento.
Fluxo de venda: estrutura similar, com taxas de pagamento dependendo do sistema de destino.

A participação na receita para parceiros é negociada separadamente assim que o volume aumenta. Integrações de alto volume geralmente obtêm preços personalizados e um contato de conformidade dedicado.

Testando MoonPay com Apidog

URLs assinadas e webhooks HMAC são os dois pontos onde a maioria das integrações da MoonPay falha, e ambos são mais rápidos de depurar em um cliente de API adequado do que no código da aplicação. O Apidog permite que você importe a especificação OpenAPI da MoonPay, armazene suas chaves do sandbox como variáveis de ambiente e execute o ciclo completo de cotação de compra, status da transação e replay de webhook sem tocar no seu backend.

Um fluxo de trabalho prático: crie um ambiente Apidog para sandbox e outro para production, crie um script para a geração de assinatura como um hook de pré-requisição usando o trecho de código Node crypto acima, e salve IDs de transações de exemplo como variáveis para que você possa pular diretamente de createTransaction para getTransactionStatus. Quando um webhook chegar em produção, copie o corpo bruto para o mock server do Apidog e reproduza-o contra seu endpoint local até que seu verificador seja aprovado. Baixe o Apidog para ter os hooks de assinatura, mock server e o alternador de ambiente em um só lugar.

FAQ

Preciso do meu próprio fornecedor de KYC além da MoonPay?Não. A MoonPay executa a verificação de identidade no lado do servidor; seu aplicativo nunca verá um documento de identificação. Se você deseja antecipar a verificação para outras partes do seu produto, consulte nossa comparação das melhores APIs de KYC.

Posso usar a MoonPay sem exibir o widget da marca deles?Sim, através da API direta ou do SDK Ramps headless, mas você precisará de uma revisão de conformidade adicional, pois o fluxo de marca cobre automaticamente muitas das divulgações exigidas. A maioria das equipes lança o widget primeiro e migra quando o volume justifica a revisão.

Quais países a MoonPay suporta?Mais de 160 países para compra e um conjunto menor (aproximadamente 50) para venda, com a disponibilidade de moeda e método de pagamento variando por região. O endpoint de moedas retorna a matriz atual por localização do usuário.

Quanto tempo leva uma transação?Compras com cartão são liquidadas na carteira do usuário em menos de cinco minutos no cenário ideal. Transferências bancárias levam de 1 a 3 dias úteis para a compensação do fiat antes que a cripto seja liberada. Transações de venda liquidam o fiat para o banco do usuário em 1 a 3 dias após as confirmações na blockchain.

O que acontece se uma entrega de webhook falhar?A MoonPay tenta novamente com um backoff exponencial por até 24 horas. Você deve retornar uma resposta 2xx somente depois de ter persistido o evento, e deduplicar pelo id, pois as tentativas podem produzir duplicatas.

O sandbox é equivalente à produção?Próximo, mas não idêntico. As restrições geográficas são relaxadas, o KYC é contornado com documentos de teste e as transações se movem entre os estados com base nos controles do painel. Sempre execute um teste de fumaça final de produção após as chaves serem emitidas.