Status e registro no banco
Uma cobrança Pix tem duas informações de estado, que aparecem lado a lado na tela e na lista:
- Situação: o ciclo de vida da cobrança (aberta, vencida, paga, cancelada).
- Registro no Banco: se o banco já recebeu e aceitou a cobrança.
Situação
| Situação | O que significa |
|---|---|
| Aberto | Cobrança criada e aguardando pagamento. Toda cobrança nasce aberta. |
| Vencido | O vencimento passou sem pagamento. |
| Pago | O banco confirmou o pagamento. A tela passa a mostrar Pago em, Quantia Paga e Mensagem do Pagador. |
| Cancelado | A cobrança foi cancelada. |
Aberto ──── vencimento passou ────► Vencido
Vencido ─── vencimento alterado ──► Aberto
Aberto ──── cancelamento ─────────► Cancelado
Vencido ─── cancelamento ─────────► Cancelado
Aberto ──── pagamento ────────────► Pago
Vencido ─── pagamento ────────────► Pago
Cancelado ─ pagamento ────────────► Pago
- Aberto → Vencido: uma rotina periódica da Kobana marca como vencidas as cobranças abertas cujo vencimento já passou. Para cobranças do tipo Cobrança, a rotina não roda aos domingos, às segundas-feiras nem no dia seguinte a um feriado, porque o vencimento que cai em fim de semana ou feriado vale até o dia útil seguinte.
- Vencido → Aberto: acontece quando uma alteração feita pela API muda o vencimento para uma data futura e o banco confirma a alteração.
- Aberto ou Vencido → Cancelado: pelo cancelamento no banco ou pela ação Marcar como cancelado.
- → Pago: quando o banco confirma o pagamento. Se o pagamento chegar depois do cancelamento, a cobrança passa de Cancelado para Pago.
Como a Kobana sabe que a cobrança foi paga
O banco avisa a Kobana quando o Pix é pago, e a Kobana também consulta de hora em hora os pagamentos das suas contas Pix. Ao receber a confirmação, a Kobana:
- marca a cobrança como Pago e grava data, valor pago, mensagem do pagador e o identificador da transação (ID End-to-End);
- cria o registro do pagamento na tela Recebimentos, com Forma de Recebimento Pix;
- se a cobrança está ligada a um boleto, dá baixa no boleto.
Uma cobrança já paga não é paga de novo: notificações repetidas do mesmo pagamento são ignoradas.
Registro no Banco
Logo depois da criação, a Kobana envia a cobrança ao banco da conta Pix. Esse envio é feito por um comando de Registro, em segundo plano.
| Registro no Banco | O que significa |
|---|---|
| Pendente | A cobrança foi criada e ainda não tem confirmação do banco. A tela mostra "Aguardando registrar no banco...". |
| Confirmado | O banco aceitou a cobrança. A Kobana grava o TX ID, o QR Code e a data do registro, e a tela passa a mostrar "Aguardando pagamento..." enquanto a cobrança estiver aberta. |
| Falha | O banco recusou o registro. A mensagem do banco aparece na coluna Mensagem da Falha da aba Comandos. |
O filtro Situação do Registro da busca também lista Ignorado, Requisitado e Rejeitado.
Na lista de cobranças, o ícone colorido ao lado da situação mostra o registro no banco; passe o mouse sobre ele para ver a situação e, quando confirmado, a data do registro.
Regras do registro:
- a cobrança precisa ter vencimento;
- a Kobana não tenta registrar cobranças vencidas há mais de 48 horas;
- a conta Pix precisa estar ativa no momento do envio;
- cobrança cancelada ou vencida não é registrada.
Comandos
Cada operação que a Kobana envia ao banco sobre uma cobrança é um comando. A aba Comandos da tela da cobrança lista todos, do mais recente para o mais antigo:
| Coluna | Conteúdo |
|---|---|
| ID | Número do comando |
| Operação | Registro, Alteração, Cancelamento, Obtenção, Sincronização ou Conclusão |
| Solicitado em | Quando o comando foi criado |
| Status | Agendado, Pendente, Interrompido, Aguardando, Processado, Confirmado ou Falha |
| Confirmado em | Quando o banco confirmou |
| Falhou em | Quando o comando falhou |
| Mensagem da Falha | Mensagem de erro do banco |
Operações de consulta (Obtenção, Sincronização e Conclusão) só são enviadas para cobranças com registro confirmado.
Cancelar uma cobrança
O menu Ações da cobrança mostra uma de duas opções:
Cancelar
Aparece quando a cobrança pode ser cancelada no banco, isto é, quando:
- o registro no banco está Confirmado;
- a cobrança não está paga nem cancelada;
- a cobrança ainda está dentro do prazo. No tipo Imediato, o prazo termina no vencimento. No tipo Cobrança, termina depois do vencimento somado aos Dias para Baixa.
Ao confirmar ("Esta ação enviará ao provedor financeiro um comando de cancelamento do Pix. Confirma?"), a Kobana cria um comando de Cancelamento e mostra "Pix enviado para cancelamento no provedor financeiro.". A situação muda para Cancelado quando o banco confirma o comando.
O cancelamento é recusado nestes casos:
| Caso | Mensagem |
|---|---|
| A cobrança já está cancelada | "Pix já cancelado." |
| A cobrança é somente leitura | "Este Pix é apenas para conciliação e não pode ser alterado diretamente." |
| A cobrança está ligada a um boleto híbrido | "Pix associado a boleto híbrido não pode ser cancelado diretamente." |
Uma cobrança Somente Leitura mostra Cancelar desabilitado, com a explicação "Este Pix é somente leitura. Não é possível cancelar.".
Marcar como cancelado
Aparece no lugar de Cancelar quando uma cobrança aberta ou vencida não pode ser cancelada no banco, por exemplo porque o registro não foi confirmado ou porque o prazo já passou. Ela muda a situação para Cancelado só na Kobana: nenhum comando é enviado ao banco. O painel avisa antes: "Esta ação marcará o Pix como cancelado na Kobana. Não haverá envio de comando ao provedor financeiro. Confirma?".
Marcar como cancelado não impede o pagamento no banco. Se o pagador pagar o QR Code depois disso e o banco confirmar, a cobrança passa a Pago.
Alterar uma cobrança
O painel não tem tela de alteração de cobrança Pix. A alteração é feita pela API v2 e vira um comando de Alteração enviado ao banco. A alteração é recusada quando a cobrança:
- já passou do prazo (vencimento mais Dias para Baixa, no tipo Cobrança, ou vencimento, no tipo Imediato);
- está cancelada ou paga;
- é somente leitura;
- está ligada a um boleto híbrido.
O Tipo de Registro não pode ser alterado.
Eventos de webhook
| Código | Quando |
|---|---|
pix.db.created | Cobrança criada |
pix.db.updated | Cobrança alterada na Kobana |
pix.db.deleted | Cobrança excluída |
pix.register.requested, pix.register.confirmed, pix.register.failed, pix.register.error | Andamento do comando de registro |
pix.update.requested, pix.update.confirmed, pix.update.failed, pix.update.error | Andamento do comando de alteração |
pix.cancel.requested, pix.cancel.confirmed, pix.cancel.failed, pix.cancel.error | Andamento do comando de cancelamento |
pix.paid | Cobrança paga |
pix.overdue | Cobrança do tipo Cobrança vencida |
Veja a lista completa e o formato dos eventos em Eventos de webhook.
Pela API
Consulta, alteração e cancelamento de cobranças Pix estão na API v2.