Primeira cobrança em 5 minutos

1. Crie uma chave de API

No painel, abra Integrações → Chaves de API e crie uma chave com os escopos charges:write e charges:read. O segredo aparece uma única vez; guarde-o no cofre de segredos do seu servidor.

2. Crie a cobrança

Envie o valor em centavos, quem vai pagar e um external_id do seu sistema. O cabeçalho Idempotency-Key é obrigatório: se a conexão cair, repita com a mesma chave e você recebe a mesma cobrança.

A resposta traz pix.copy_paste e pix.qr_code_base64 para mostrar ao pagador, e expires_at com o fim da validade do QR.

3. Receba o webhook

Cadastre a URL do seu servidor em Integrações → Webhooks e marque charge.paid. Quando o banco confirmar o pagamento, a Mainum faz um POST assinado com a cobrança completa em data.object, incluindo paid_by e end_to_end_id.

1. Leia o corpo cru da requisição e confira a assinatura X-Mainum-Signature antes de qualquer coisa.
2. Ignore eventos cujo X-Mainum-Event-Id você já processou.
3. Responda 2xx rápido e faça o trabalho pesado depois, numa fila sua.

Ver o catálogo de eventos e o código de verificação →

4. Confira quando precisar

Webhook é o caminho normal, mas nunca a única fonte. Para conferir uma cobrança, consulte pelo ID; para recuperar eventos perdidos, use a lista de eventos.