Cobranças, cancelamento e retentativa

A cobrança de Pix Automático é o débito de um período de uma recorrência. Você cria a cobrança informando o valor e a data, e o banco debita a conta do pagador conforme a autorização dada na recorrência.

A cobrança é gerenciada pela API v2.

Antes de começar

A recorrência precisa estar registrada no banco. Uma cobrança para uma recorrência ainda sem registro é recusada com "deve estar registrada no provedor financeiro".

Campos

Campo	Obrigatório	Descrição
Recorrência	Sim	Recorrência a que a cobrança pertence. A conta Pix Automático, a conta financeira, o recebedor e o devedor vêm dela.
Valor	Sim	Maior que zero.
Data de Expiração	Sim	Data da cobrança. Precisa ser de hoje em diante.
Política de Retentativa	Sim	Não permitir ou Permitir (3 tentativas em 7 dias).
Próximo Dia Útil	Não	Indica ao banco se a data da cobrança deve ser ajustada para dia útil.
Informação Adicional	Não	Texto livre enviado ao banco. A Kobana envia até 140 caracteres.
TXID	Não	Identificador da transação, de 26 a 35 letras e números. Se ficar em branco, a Kobana gera um.
Devedor: e-mail e endereço	Não	Contatos do devedor. No máximo um e-mail e um endereço. Nome e documento vêm da recorrência.
ID Externo	Não	Identificador do seu sistema. Não pode se repetir na mesma conta Kobana.
Etiquetas e Dados Personalizados	Não	Informações livres para organizar e buscar.

Situação no Provedor

Situação	O que significa
Pendente	Criada na Kobana, ainda sem registro no banco
Criado	Registrada no banco
Ativo	Ativa no banco, aguardando o pagamento
Pago	O débito foi feito
Expirado	A cobrança expirou sem pagamento
Rejeitado	O banco recusou a cobrança
Cancelado	A cobrança foi cancelada

Pendente ─► Criado ─► Ativo ─► Pago
Criado ───► Rejeitado, Expirado ou Cancelado
Ativo ────► Rejeitado, Expirado ou Cancelado

Quando há rejeição ou cancelamento, a cobrança guarda o código, a data e a descrição.

Pagamento

Quando o banco informa que a cobrança foi paga, a Kobana:

1. muda a situação para Pago;
2. cria o recebimento na tela Recebimentos, com Forma de Recebimento Pix Automático e o valor da cobrança;
3. dispara o evento charge.automatic_pix.pix.paid.

A data do recebimento é a data de pagamento da tentativa paga, quando houve retentativa, ou a data em que a situação passou a Pago. Cada cobrança gera no máximo um recebimento.

Cancelar uma cobrança

Pela API, uma cobrança registrada e na situação Criado ou Ativo pode ser cancelada. A Kobana envia um comando de cancelamento ao banco, e a situação passa a Cancelado quando o banco confirma. Comandos ainda agendados para a mesma cobrança são interrompidos.

Retentativa

Uma cobrança que não foi paga pode ser tentada de novo numa nova data. Pela API, a retentativa é aceita quando:

• a cobrança está registrada no banco;
• a situação é Ativo, Expirado ou Rejeitado;
• a Política de Retentativa da cobrança é Permitir (3 tentativas em 7 dias);
• a nova data é futura.

A Kobana envia um comando de Retentativa ao banco com a nova data. Comandos ainda agendados para a mesma cobrança são interrompidos.

Cada tentativa fica registrada na cobrança, com tipo (Agendado, Não Agendado ou Com Reflexão), situação (Solicitado, Agendado, Pago, Cancelado, Rejeitado ou Expirado), identificador da transação, data de pagamento e, quando houver, o motivo da rejeição.

Eventos de webhook

Código	Quando
charge.automatic_pix.pix.db.created, .db.updated, .db.deleted	Cobrança criada, alterada ou excluída na Kobana
charge.automatic_pix.pix.register.requested, .confirmed, .failed, .error	Andamento do registro no banco
charge.automatic_pix.pix.cancel.requested, .confirmed, .failed, .error	Andamento do cancelamento no banco
charge.automatic_pix.pix.pending, .created, .active, .paid, .expired, .rejected, .canceled	Mudança da Situação no Provedor
charge.payment.db.created	Recebimento criado na tela Recebimentos

Pela API

Cobranças de Pix Automático, cancelamento e retentativa estão na API v2.