Cliente diz "paguei", mas cobrança na Kontato continua pendente. Frustrante mas geralmente resolve em 5min.
Diagnóstico — fonte de verdade é o Asaas
A Kontato só sabe que cobrança foi paga quando recebe sinal do Asaas (webhook). Se o sinal não chegou, mesmo cliente tendo pago, a Kontato continua mostrando "pendente".
Por isso, verificar direto no Asaas é o passo 1 sempre.
Abre o painel Asaas (https://www.asaas.com).
Vai em Cobranças → busca pela cobrança (por valor + data + cliente).
Verifica o status real:
- Recebido ✅ → cliente pagou de fato. Webhook se perdeu, vai pra fix abaixo.
- Pendente ⏳ → cliente NÃO pagou (ele se enganou ou pagou em conta errada).
- Vencido ⚠️ → passou data de vencimento sem pagamento.
Cliente realmente pagou (Asaas confirma) mas Kontato não atualizou
Webhook se perdeu. Fix manual:
Na Kontato, vai em /cobrancas → click na cobrança.
Click "Marcar como pago manualmente".
Confirma. Status vira pago na Kontato.
⚠️ Importante: marcação manual não dispara:
- Trigger fidelidade (cliente não ganha selo)
- Comissão indicação 20% (indicador não recebe)
- Mensagem automática "Recebido!" pro cliente
Se algum desses importa, ajusta manualmente:
- Fidelidade: em
/clientes/[id]→ cartão fidelidade → adiciona selo manualmente - Comissão: notifica suporte pra revisar (raro caso)
- Mensagem: envia manualmente pelo cockpit
Cliente pagou em CHAVE PIX errada
Se cliente fez Pix pra outra chave (não a sua), o pagamento não cai na sua conta Asaas — então Asaas nem registra.
Fix:
- Cliente precisa recuperar o valor com quem recebeu (instituição financeira sempre conserta esse erro em poucos dias)
- Você gera novo Pix pra cliente pagar certo
Polling Pix expirou (5min)
Lembre que maquininha faz polling Asaas a cada 3s por 5 minutos após criar Pix. Após isso:
- Polling para
- Tela continua "Aguardando" mas inerte
- Se cliente paga depois (10min, 1h, 1 dia), webhook ainda chega → status atualiza na Kontato
⚠️ Mas se webhook se perdeu + polling já parou → status fica "pendente" pra sempre. Você tem que marcar manual conforme acima.
Webhook Asaas configurado errado
Se MUITAS cobranças ficam "pendentes" sistematicamente, talvez o webhook da Kontato no Asaas está mal configurado:
Abre Asaas → Configurações → Webhooks.
Verifica se existe um webhook ativo apontando pra https://kontato.themagicbox.app/api/webhooks/asaas/[seu-token].
Verifica se tá marcado pra eventos PAYMENT_RECEIVED, PAYMENT_CONFIRMED, PAYMENT_OVERDUE.
Na Kontato, vai em Configurações → Cobranças → Webhook URL e copia. Confere se bate com a do Asaas.
Se URL não bate → atualiza no Asaas. Próximas cobranças confirmam normalmente.
Logs de webhook (debug avançado)
Em Configurações → Cobranças → Logs de webhook (admin), você vê:
- Lista das últimas 100 chamadas recebidas do Asaas
- Status processamento (OK / erro)
- Payload completo (pra debug)
Útil pra confirmar se Asaas mandou o webhook (ou se realmente perdeu).
Cobrança vencida — cliente pagou só hoje
Cliente paga após o vencimento. Asaas aceita (Pix não tem vencimento real) e dispara PAYMENT_RECEIVED normal. Status na Kontato muda de vencido direto pra pago.
⚠️ Mas se você cancelou a cobrança entre o vencimento e o pagamento, cliente pagou na boa mas você não vai conseguir conciliar. Status fica órfão.
Fix:
- Não cancela cobranças que cliente "ainda pode pagar"
- Se cancelou, gera nova cobrança (mesmo valor, mesma descrição) e cliente confirma essa
- Estorno do Pix antigo (do já cancelado) você faz no Asaas (gera Pix de devolução pra cliente)