Primeira integração

Pré-requisitos

Tenha uma conta MingoPay, acesso à área API do dashboard e um backend capaz de fazer requisições HTTPS. Para receber eventos, configure uma URL HTTPS pública. Em desenvolvimento local, o backend usa http://localhost:4000 por padrão.

Crie uma chave mp_test_ com payment_intents:write e payment_intents:read. Guarde o token somente no servidor; ele aparece uma única vez.

1. Criar uma cobrança

Configure API_BASE_URL para o endereço do backend do seu ambiente. Envie valor inteiro em centavos, method pix, um CPF/CNPJ válido do pagador e uma Idempotency-Key nova para a tentativa.

curl -X POST "$API_BASE_URL/v1/payment-intents" \
  -H "Authorization: Bearer $MINGOPAY_API_KEY" \
  -H "Idempotency-Key: pedido-1024-cobranca-001" \
  -H "Content-Type: application/json" \
  -d '{"externalReference":"pedido_1024","amountCents":14990,"method":"pix","payer":{"name":"Cliente Exemplo","taxId":"52998224725"}}'

2. Mostrar o PIX

A resposta HTTP 201 inclui id, status e pix.copyPasteCode. Mostre o código copia e cola ao cliente e armazene o id da cobrança junto ao seu pedido. A consulta posterior por id retorna os dados da cobrança, mas não repete pix.copyPasteCode; preserve esse código no momento da criação se precisar reexibi-lo. O estado pending ainda não significa pagamento recebido.

3. Confirmar no sandbox

No sandbox não há PIX bancário real. Use o id recebido e a mesma chave mp_test_ para simular o pagamento.

curl -X POST "$API_BASE_URL/v1/sandbox/payment-intents/$PAYMENT_ID/confirm" \
  -H "Authorization: Bearer $MINGOPAY_API_KEY"

4. Reconciliar

Valide o webhook payment_intent.paid no seu servidor. Quando precisar consultar, use GET /v1/payment-intents/:id. Só libere o pedido após um estado paid confirmado.

Antes de produção, revise o provedor habilitado, chave mp_live_, endpoint de produção e tratamento de falhas.