Pagamentos, devoluções e MED

Pix sem cobrança

Um Pix que não quita uma cobrança (pago depois de expirar, em duplicidade, direto na chave…) chega como pagamento unmatched (evento payment.unmatched, com o motivo). Você tem um prazo (padrão 72 horas, em auto_refund_at) para decidir:

• aceitar — POST /v1/payments/{id}/accept — e ficar com o valor; ou
• devolver — POST /v1/refunds.

Sem decisão, o valor é devolvido automaticamente ao pagador.

Devoluções

curl -X POST "https://api.exemplo.com.br/v1/refunds" \
  -H "Authorization: Bearer $PIX_API_KEY" -H "Idempotency-Key: $(uuidgen)" -H "Content-Type: application/json" \
  -d '{"payment_id": "pay_…", "amount": "50.00", "reason": "Item fora de estoque"}'

A devolução começa processing e termina succeeded ou failed (eventos refund.succeeded / refund.failed). Pode ser parcial, em mais de uma vez, até o valor pago. Em devolução, a taxa é estornada na proporção do valor devolvido.

MED

O Mecanismo Especial de Devolução do Banco Central permite ao banco do pagador contestar um Pix por suspeita de fraude. O valor pode ser bloqueado (evento med.blocked; o pagamento traz med_blocked: true e não pode ser devolvido por você) e depois liberado (med.released) ou devolvido pelo MED (charge.refunded).

Quando o bloqueio chega, você recebe um e-mail e o caso aparece no painel, em Contestações MED, com o prazo para mandar as evidências da venda: o que foi vendido, para quem e como foi entregue, com documentos (nota fiscal, comprovante de entrega, conversa com o cliente). A plataforma encaminha ao banco. As evidências ajudam, mas o resultado não é garantido — em 2025, a maior parte dos MED terminou com devolução ao pagador.