Integração Pix Automático - modobank
Introdução
Esta documentação detalha o processo de configuração do Pix Automático à sua integração modobank - Pix Avulso no Sistema. O Pix Automático simplifica, agiliza e traz mais segurança para transações periódicas, como mensalidades e assinaturas.
Os principais benefícios do Pix Automático são:
- Redução da inadimplência: Débitos automáticos e tentativas extras de cobrança aumentam a taxa de recebimento.
- Otimização do fluxo de caixa: Pagamentos mais previsíveis facilitam o planejamento financeiro.
- Menor custo operacional: Menos gastos com boletos, intermediários e taxas.
- Maior alcance e inclusão financeira: Funciona para qualquer usuário do Pix, inclusive sem cartão de crédito.
- Melhoria da experiência do cliente: Pagamento automático, sem autenticação repetitiva, mas com controle total pelo pagador.
- Segurança e confiabilidade: Supervisão do Banco Central e proteção extra via Mecanismo Especial de Devolução (MED).
Funcionalidade Principal
O Pix Automático permite a realização de pagamentos avulsos e recorrentes de forma automática, sem a necessidade de autenticação a cada transação. A autorização prévia concedida pelo usuário pagador ao recebedor garante que débitos futuros sejam realizados automaticamente na data prevista, trazendo agilidade, praticidade e segurança para empresas e clientes.
Detalhes de funcionamento - Pix Automático
- Requer autorização prévia do pagador para que a cobrança recorrente seja debitada automaticamente;
- Funciona para valores fixos ou variáveis, definidos pelo recebedor a cada ciclo de cobrança;
- O agendamento e débito ocorrem conforme as regras estabelecidas pelo Banco Central e pelo PSP do pagador;
- Em caso de saldo insuficiente, podem ocorrer novas tentativas de cobrança, conforme política definida pelo recebedor;
- O cancelamento da autorização impede débitos futuros, mas não afeta pagamentos já agendados;
- Pode ser integrado via QR Code Composto ou solicitações diretas de autorização, seguindo as jornadas definidas no Manual de Padrões do Pix;
- Diferencia-se do Pix tradicional por não exigir a execução manual da transação a cada pagamento.
Passo a Passo: como configurar o Pix Automático - modobank
- Acesse o menu Sistema > Cadastros > Financeiro > Carteira de Cobrança
- Selecione a carteira de cobrança desejada, e clique em Editar
- Siga para a aba Configurações Pix
- Localize o parâmetro Utilizar Pix recorrente e marque-o como Sim:
- Sim: ao marcar como Sim, ao finalizar o pagamento via Pix, o cliente receberá uma solicitação para ativar a recorrência, permitindo a cobrança automática nos próximos vencimentos.
- Não: ao manter marcado como Não, a funcionalidade do Pix automático (recorrente) não estará disponível ao cliente final.
- Ativando o parâmetro acima, também ficará visível o parâmetro Repetir tentativa de cobrança para Pix recorrente, marque-o conforme necessário:
- Sim: ao marcar como Sim, a cobrança recorrente poderá realizar uma nova tentativa de débito, caso aconteça algum erro na primeira tentativa.
- Não: ao marcar como Não, a cobrança Pix tentará debitar somente uma vez.
- Após configuração destes parâmetros, a carteira já está pronta para seguir emitindo as cobranças Pix com a inclusão da recorrência.
- Fim.
Com essa configuração, sempre que o cliente final efetuar um pagamento via Pix, será exibida em seu aplicativo bancário a opção de ativar a recorrência (opcional), permitindo que as próximas cobranças sejam realizadas automaticamente nos vencimentos seguintes.
Fluxo do Processo
Tarefa de Ativação de Recorrência
Após a ativação dos parâmetros de recorrência na carteira de cobrança, é fundamental ser configurada a tarefa de recorrência. Esta tarefa será a responsável por realizar a criação da cobrança a partir da recorrência ativa em contratos no Sistema. Ela será executada diariamente, e aplicará a criação da cobrança para todos as cobranças recorrentes com vencimento de até 10 dias, a partir da data de sua execução.
Abaixo, acompanhe o passo a passo de configuração da tarefa:
- Vá até o menu Ferramentas.
- Clique em Ferramentas.
- Acesse Agenda de tarefas.
- Clique em Novo.
- Em Tarefa, selecione Ativação de recorrência Pix para contratos com ID de recorrência vinculado.
- Minuto (0-59):
- Tipo: Selecione a opção Valor
- Valor: Insira o número 0
- Hora (0-23):
- Tipo: Selecione a opção Valor
- Valor: Insira o número 1
- Dia do mes (1-31):
- Tipo: Selecione a opção Valor
- Valor: Não preencher
- Mes (1-12):
- Tipo: Selecione a opção Valor
- Valor: Não preencher
- Dia da semana (0-6) 0=dom, 1=seg...:
- Tipo: Selecione a opção Valor
- Valor: Não preencher
- Minuto (0-59):
- Finalize clicando no botão Salvar.
Com a configuração acima, a tarefa fica configurada para executar todos os dias às 01:00 da manhã.
O Cancelamento de Pix Recorrente está presente na versão Beta do sistema. Sua disponibilidade na versão Estável será a partir de Fevereiro de 2026.
Tarefa para Atualização de Status do Pix Automático
Desenvolvida tarefa automática diária para consultar e atualizar o status das recorrências Pix automático, sem depender exclusivamente do webhook da modobank. A tarefa verifica contratos com status de recorrência Pix em "Aguardando aprovação" ou "Aprovada" e atualiza conforme necessário.
Tarefas criadas:
Cancelamento de Pix Recorrente
Implementada lógica para cancelar automaticamente a recorrência do Pix quando houver alteração da data de vencimento em contratos através da Alteração Wizard ou Assistente de Alteração de Contrato. Este procedimento assegura o cumprimento das regras de funcionamento e registro de cobranças estabelecidas pela integração com o gateway de pagamento.
Regras de Funcionamento
- Quando o parâmetro do Pix recorrente está ativo, ao realizar um pagamento via Pix o cliente receberá em seu aplicativo bancário uma solicitação opcional para ativar a recorrência.
- Se o pagador ativar a recorrência, o ID da recorrência será gravado no contrato recorrente ou de origem vinculado ao boleto, no campo Token.
- A cobrança recorrente só será disponibilizada se o boleto estiver vinculado a um contrato recorrente (financeiro convencional) ou a um contrato de origem (novo conceito financeiro). Boletos de financeiro avulso ou sem contrato vinculado seguirão o fluxo normal de pagamento via Pix avulso.
- No Sistema, é necessário configurar a tarefa de recorrência do Pix, que será responsável por executar as cobranças recorrentes com vencimento de até 10 dias a partir da data de sua execução. Ao executar, as informações da criação da cobrança serão registradas no histórico boleto, incluindo a requisição do sistema e resposta da instituição financeira (request e response).
- Quando a cobrança recorrente for liquidada, a instituição deve enviar um webhook ao Sistema, realizando o recebimento da cobrança (contas a receber). Se o pagamento não ocorrer, a recorrência deverá ser cancelada, com base no webhook de cancelamento enviado pela modobank. Ao cancelar, será desvinculado o ID da recorrência no Contrato, e serão canceladas as cobranças recorrentes, caso existam.
No recebimento , cancelará as cobranças vinculadas a outras integrações:
- Pedido de baixa para remessa e retorno
- Requisição de cancelamento para Gateways e APIs
- Requisição de cancelamento para Pix cobrança modobank
- Quando a cobrança recorrente for comunicada (registrada) e o boleto for recebido manualmente ou por integração, cancelado ou renegociado, será enviada uma requisição de cancelamento da recorrência.
- Quando o contrato possuir uma recorrência ativa, não serão iniciadas novas requisições de recorrência, mesmo que o pagamento seja realizado por Pix cobrança.
- Quando o contrato estiver vinculado a uma recorrência de cartão de crédito, não será criada uma nova recorrência caso o pagamento seja feito via Pix.
- Quando um boleto vinculado a uma recorrência Pix for pago com cartão de crédito, não será permitida a ativação da recorrência de cartão de crédito.
FAQ - Pix automático modobank
Caso o pagador não tenha saldo disponível no dia do vencimento, o sistema realiza nova tentativa de cobrança no dia seguinte, aplicando automaticamente os juros e a multa configurados na carteira Pix?
- O Pix automático não tem incidência de Juros e Multa (semelhante ao débito automático), que se aplica somente aos pagamentos avulsos. A cobrança do Pix Automático será efetuada até duas vezes na data de vencimento da fatura. Se o saldo bancário for insuficiente, a transação não será processada. Além disso, serão realizadas até três tentativas adicionais nos dias subsequentes, conforme as diretrizes estabelecidas pelo Banco Central.
Essa integração utiliza a jornada 4, na qual, ao ler o QR Code, o banco do pagador disponibiliza a opção de ativar a cobrança automática?
- Sim. Essa integração segue a jornada 4. Nesse fluxo, o pagador realiza ou agenda o pagamento de uma cobrança e, somente após a confirmação da operação, o banco oferece a opção de habilitar o Pix Automático como forma de pagamento para cobranças futuras.
Considerações Finais
Em resumo, o funcionamento da recorrência via Pix garante maior automação e controle nos processos de cobrança, permitindo que o cliente opte pela ativação da recorrência diretamente em seu banco, enquanto o Sistema gerencia a execução, registro e acompanhamento das cobranças. Além disso, a integração com webhooks e regras específicas de cancelamento assegura que não haja conflitos entre diferentes modalidades de cobrança, mantendo a consistência das informações nos contratos e evitando duplicidade de recorrências.