Guia de integração Moonip

Bem-vindo. Este guia é tudo que você precisa para receber pagamentos pela Moonip — da primeira chamada de API até os webhooks assinados chegando em produção.

#O que a Moonip resolve

A Moonip é um gateway de pagamentos Pix-first. Você cria uma Cobrança (charge) por uma única API canônica e nós roteamos para o PSP/adquirente certo por trás; a resposta já traz o BR Code e o QR Code prontos para renderizar no seu checkout. Cartão, MB WAY e Multibanco existem na mesma conta quando habilitados, mas o Pix é o ponto de partida de toda integração nova.

Sua aplicação nunca fala com o PSP direto, nunca guarda dado de cartão e nunca precisa mudar quando trocamos ou adicionamos um provedor — o campo provider e qualquer identificador de PSP são removidos pelo serializador antes da resposta chegar até você.

text

┌────────────┐               ┌──────────┐                ┌─────────────┐
│            │ POST /charges │          │  roteamento    │  PSP/       │
│  Seu app   ├──────────────▶│  Moonip   ├───────────────▶│  adquirente │
│            │◀──────────────┤          │◀───────────────┤  (interno)  │
└──────┬─────┘  BR Code / QR └────┬─────┘   status       └─────────────┘
       │                          │
       │   webhook assinado       │
       │◀─────────────────────────┘
       │      charge.paid
       ▼
  Pedido liberado

#Meios de pagamento

Meio	Região	Fluxo	Liquidação típica
`PIX`	Brasil	QR Code + copia e cola	Na hora (segundos)
`CREDIT_CARD`	Global	Redirect hospedado (3DS)	D+1 a D+30
`MBWAY`	Portugal	Push no celular + polling	No mesmo dia
`MULTIBANCO`	Portugal	Entidade / Referência	1–3 dias úteis
`BOLETO`	Brasil	Código de barras + PDF	1–3 dias úteis

O Pix é o trilho principal para lojista brasileiro e o fluxo por onde toda integração nova deve começar.

A disponibilidade é POR CONTA. Os meios acima são habilitados individualmente para a sua conta — um meio para o qual você não foi habilitado é recusado na criação da cobrança, não no checkout. Confirme com seu contato na Moonip quais trilhos estão ativos antes de construir em cima de um deles.

#Leia nesta ordem

Primeiros passos — autenticação, ambientes, convenções e sua primeira chamada
Pix — o fluxo Pix de ponta a ponta, com código
Webhooks — registrar endpoints, verificar assinatura, lidar com retentativa
Erros — formato do erro, mapa de status e estratégia de retry
Referência da API — cada endpoint, cada campo, cada status

Com o Pix funcionando de ponta a ponta e com webhook, os outros meios são variações pequenas do mesmo fluxo:

Cartão
MB WAY
Multibanco

Receber é metade do sistema. A outra metade é tirar o dinheiro:

Saques — Pix out, TED (Saque)
Falhas de saque — o contrato da recusa: INSUFFICIENT_BALANCE, os códigos failure_code e a falta de liquidez do processador
Disputas e MED — contestação Pix (MED do BACEN): retenção, API e webhooks de caso MED, contestação, envio de evidências e desfechos

Reembolsos não fazem parte da API: são feitos no painel administrativo da Moonip (POST /v1/payments/{id}/refund responde 403 para toda chave de API — error.code "forbidden", mensagem com o prefixo do marcador REFUND_ADMIN_ONLY).

Operando sua conta:

Chaves de API — emitir, listar, girar e revogar chaves pelo painel ou pela API
SDKs oficiais — Node.js, Python, PHP e .NET

#O contrato que você usa

Este guia documenta o contrato público v1 da Moonip: o cabeçalho Authorization: Bearer com chaves ak_test_* / ak_live_* (o cabeçalho legado apikey continua aceito), POST /v1/charges devolvendo um id ch_…, e os cabeçalhos X-Moonip-* nos webhooks. É essa a superfície — não existe nada mais antigo que você precise conhecer.

Vale notar alguns caminhos de recurso: saque fica em /v1/withdrawals, o saldo em /v1/wallets e a lista de cobranças com paginação por cursor em /v1/charges. Se um apelido canônico /v1/payouts entrar mais tarde, o caminho atual continua funcionando e passa a mandar cabeçalhos Deprecation / Sunset bem antes de qualquer remoção.

#Sandbox

Sandbox — o mesmo host e o mesmo contrato de produção, com uma chave ak_test_*: a cobrança vai para o simulador, os artefatos carregam a marca SANDBOX, e POST /v1/payments/{id}/confirm-sandbox força o PAID para você testar webhook de ponta a ponta.

#Precisa de ajuda?

Escreva para suporte@moonip.io com o seu request_id — todo erro da API traz um, e ele localiza a requisição exata no nosso log.

Consultas periódicas e limites