Recorrências e localizações
A recorrência é o acordo de Pix Automático com um pagador: quem paga, qual contrato, de quanto em quanto tempo, qual valor, quando começa e quando termina. É a recorrência que o pagador autoriza no banco dele. Depois de autorizada, as cobranças de cada período são criadas a partir dela.
A recorrência é gerenciada pela API v2.
Campos
| Campo | Obrigatório | Descrição |
|---|---|---|
| Conta Pix Automático | Sim | Conta que registra a recorrência. A conta financeira vem dela. |
| Número do Contrato | Sim | Identificador do contrato com o pagador. Até 35 caracteres. |
| Descrição | Não | Até 35 caracteres. |
| Devedor | Sim | Nome, tipo e número do documento (CPF ou CNPJ) de quem paga. O documento é obrigatório. |
| Data de Início | Sim | Não pode ser no passado. |
| Termo da Recorrência | Sim | Indefinido (sem data de término) ou Fixo (com data de término). |
| Data de Término | Só no termo Fixo | Precisa ser posterior à data de início. No termo Indefinido, deve ficar em branco. |
| Ciclo | Sim | Semanal, Mensal, Trimestral, Semestral ou Anual. |
| Tipo de Termo de Valor | Sim | Fixo (valor definido na recorrência) ou Variável (valor definido em cada cobrança). |
| Valor | Só no valor Fixo | Valor de cada cobrança. No valor Variável, deve ficar em branco. |
| Valor Mínimo | Não | Valor mínimo das cobranças. Não pode ser usado junto com Valor. |
| Política de Retentativa | Sim | Não permitir ou Permitir (3 tentativas em 7 dias). Define se cobranças não pagas podem ser tentadas de novo. |
| Código do Convênio | Não | Até 60 caracteres. |
| ID Externo | Não | Identificador do seu sistema. Não pode se repetir na mesma conta Kobana. |
| Localização e Pix Associado | Não | Usados nas jornadas por QR Code. Veja Localizações. |
Jornadas de autorização
A Jornada é a forma como o pagador autorizou a recorrência. Ela é informada pelo banco; até lá, a recorrência fica com a jornada Aguardando Definição.
| Jornada | Como o pagador autoriza |
|---|---|
| Notificação Externa | Pela solicitação enviada ao banco do pagador |
| Leitura de QR Code | Lendo o QR Code da recorrência |
| QR Composto - Pagamento Imediato | Lendo um QR Code que junta a autorização e o pagamento de uma cobrança Pix imediata |
| QR Composto - Com Vencimento | Lendo um QR Code que junta a autorização e uma cobrança Pix com vencimento |
Situação no Provedor
| Situação | O que significa |
|---|---|
| Pendente | Recorrência criada na Kobana, ainda sem registro no banco |
| Criado | Registrada no banco, aguardando a autorização do pagador |
| Aprovado | O pagador autorizou a recorrência |
| Rejeitado | O pagador ou o banco recusou a autorização |
| Expirado | A recorrência expirou |
| Cancelado | A recorrência foi cancelada |
Pendente ─► Criado
Criado ───► Aprovado
Criado ───► Rejeitado
Criado ───► Expirado
Aprovado ─► Expirado
Criado ───► Cancelado
Aprovado ─► Cancelado
Rejeitado, Expirado e Cancelado são finais. Quando há rejeição ou cancelamento, a recorrência guarda o código, a origem (Recebedor, Provedor do Recebedor, Pagador ou Provedor do Pagador), a data e a descrição. Exemplos de códigos de cancelamento: ACCL (conta encerrada), DCSD (usuário pagador declinou autorização), SLCR (solicitação do recebedor), SLDB (solicitação do pagador).
Alterar uma recorrência
Pela API, uma recorrência registrada e na situação Criado ou Aprovado aceita um comando de alteração no banco para:
- Data de Início;
- nome do devedor;
- Pix Associado;
- Localização.
Em qualquer situação, você também pode mudar ID Externo, Etiquetas e Dados Personalizados, que ficam só na Kobana.
Cancelar uma recorrência
Pela API, uma recorrência registrada e na situação Criado ou Aprovado 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 recorrência são interrompidos.
Localizações
A localização é um endereço (URL) que o banco gera para a recorrência e que vai dentro do QR Code de autorização. Ela é usada nas jornadas por QR Code.
- A localização é criada numa conta Pix Automático e registrada no banco em segundo plano. Até o banco confirmar, ela não tem o identificador do banco nem a URL.
- Uma recorrência só aceita uma localização já registrada e da mesma conta Pix Automático.
- A URL tem no máximo 77 caracteres.
- Uma localização cujo registro não se concluiu não é reenviada: crie uma nova.
Para o QR Composto, a recorrência precisa de uma localização registrada e de um Pix Associado: uma cobrança Pix aberta, com registro Confirmado, TX ID e QR Code.
Eventos de webhook
| Código | Quando |
|---|---|
charge.automatic_pix.recurrence.db.created, .db.updated, .db.deleted | Recorrência criada, alterada ou excluída na Kobana |
charge.automatic_pix.recurrence.register.requested, .confirmed, .failed, .error | Andamento do registro no banco |
charge.automatic_pix.recurrence.update.requested, .confirmed, .failed, .error | Andamento da alteração no banco |
charge.automatic_pix.recurrence.cancel.requested, .confirmed, .failed, .error | Andamento do cancelamento no banco |
charge.automatic_pix.recurrence.pending, .created, .approved, .rejected, .expired, .canceled | Mudança da Situação no Provedor |
charge.automatic_pix.location.db.created, .db.updated, .db.deleted | Localização criada, alterada ou excluída |
charge.automatic_pix.location.register.requested, .confirmed, .failed, .error | Andamento do registro da localização |
Pela API
Recorrências e localizações estão na API v2.