Débito direto SEPA com autorização online: documentação do módulo PrestaShop
Instalar, configurar e utilizar o módulo de débito direto SEPA: mandato assinado online com prova selada, ficheiro pain.008 validado, planos recorrentes, rejeições e RGPD.
Apresentação
O módulo dfsepadebit acrescenta o débito direto SEPA como meio de pagamento ao PrestaShop 1.7.8, 8 e 9. O cliente assina um mandato online durante a encomenda, com um código recebido por e-mail, sem sair da página de pagamento. Cada encomenda, cada prestação de um plano e cada débito pontual torna-se uma cobrança pré-notificada ao cliente. Gera o ficheiro pain.008 e carrega-o no portal do seu banco. Depois importa os ficheiros de retorno para atualizar os pagamentos e as rejeições.
O módulo não se liga ao seu banco nem envia dados a terceiros: os fundos chegam diretamente à sua conta.

Novidades da 2.0.0: assinatura online corrigida (falhava na 1.1.0 com o PrestaShop 8 e 9), compatibilidade com o PrestaShop 1.7.8, mandatos pontuais (OOFF), sequência FNAL, pain.008.001.08 por predefinição, validação de cada ficheiro com o esquema oficial ISO 20022, PDF do mandato selado e histórico de auditoria encadeado, ficheiros bancários cifrados e nunca enviados por e-mail, permissões por perfil de funcionário, assistente de arranque e configuração em 5 separadores.
Requisitos
- Identificador de credor SEPA e contrato de emissão de débitos diretos SEPA, a pedir ao seu banco. Indique o esquema B2B se cobrar a empresas.
- O formato de ficheiro aceite pelo banco (pain.008.001.08 ou pain.008.001.02) e o seu prazo de entrega (em geral 1 dia útil TARGET antes da data de cobrança).
- Uma loja com o euro ativado: o meio de pagamento só aparece em carrinhos em euros.
- PrestaShop 1.7.8 a 9.x, PHP 7.1 a 8.5 com a extensão OpenSSL (cifragem AES-256-GCM dos IBAN e dos ficheiros).
- Uma tarefa cron diária (alojamento ou serviço externo) para os planos, os ficheiros automáticos e as confirmações de pagamento.
Instalação e atualização
- Em Módulos > Gestor de módulos, clique em Carregar um módulo e selecione
dfsepadebit-2.0.0.zip. - O módulo cria as suas tabelas, dois estados de encomenda («Débito direto SEPA agendado» e «Débito direto SEPA rejeitado») e o menu Vender > Débito direto SEPA: Painel, Mandatos, Cobranças, Planos recorrentes e Ficheiros bancários.
- Abra a configuração. O assistente de arranque no topo da página indica o que falta: nome e morada completa do credor, identificador de credor, IBAN, euro ativado, tarefa diária e primeiro ficheiro aceite pelo banco. Enquanto o credor não estiver completo, o meio de pagamento fica oculto.
- Copie o URL de cron apresentado na configuração e agende-o uma vez por dia. O botão Novo URL de cron gera outro e invalida o anterior.

Atualização a partir da 1.1.0: carregue o novo ZIP por cima do anterior. Os mandatos, cobranças, planos, ficheiros bancários e definições são mantidos, incluindo o formato pain.008.001.02 se o tinha escolhido. A atualização recalcula as impressões dos IBAN, cifra os ficheiros já gerados, abre o histórico de auditoria de cada mandato e muda o nome dos estados de encomenda que mantinham o nome original. Os mandatos assinados com a 1.1.0 não têm PDF selado: o PDF é regenerado a partir da prova original e identificado como cópia regenerada.
Configuração
A configuração está dividida em 5 separadores.
Credor
Nome do credor (tal como aparecerá nos extratos dos clientes), identificador de credor, IBAN da conta creditada, BIC (opcional no EEE) e morada completa: rua, código postal, localidade e país são obrigatórios porque figuram no mandato. O identificador é verificado com os seus dígitos de controlo (MOD 97-10) e o IBAN com os dígitos de controlo e o comprimento do país.
Autorizações e checkout
- Esquema das novas autorizações: SEPA B2B (entre empresas, sem direito a reembolso, o devedor tem de registar o mandato no seu banco) ou SEPA Core (qualquer cliente, reembolso possível durante 8 semanas).
- Tipo de pagamento das autorizações assinadas online: recorrente (o cliente assina uma vez e o mandato serve para as encomendas e planos seguintes) ou pontual (um mandato por encomenda, válido para um único débito).
- Prefixo das referências de autorização: letras e algarismos, no máximo 8 caracteres (DF por predefinição).
- Assinatura com um código enviado por email: recomendada, reforça o processo de prova. Desativada, o cliente assina com uma simples caixa de verificação.
- Anexar o PDF da autorização ao e-mail de confirmação: a cópia anexada mostra o IBAN parcialmente oculto. A cópia completa continua disponível na conta do cliente.
- Apenas para clientes com nome de empresa: o meio de pagamento só é proposto se a morada de faturação tiver uma empresa.
- Grupos de clientes autorizados, montantes mínimo e máximo da encomenda.
- Exposição máxima por cliente: cobranças ainda não pagas mais o carrinho atual. Acima deste valor, o meio de pagamento fica oculto para esse cliente.
- Ocultar após rejeições nos últimos 12 meses: 2 por predefinição, 0 para desativar.
Cobranças e ficheiros bancários
- Prazo de pré-notificação: os rulebooks fixam 14 dias de calendário, salvo outro prazo acordado com o devedor. O módulo propõe 2 dias: um prazo inferior a 14 dias tem de constar das suas condições de venda. O prazo figura no texto do mandato. Uma encomenda é cobrada no fim deste prazo.
- Prazo de entrega do seu banco, em dias úteis TARGET.
- Formato do ficheiro: pain.008.001.08 por predefinição (versão 2019 da ISO 20022, usada pelas orientações de implementação do EPC em vigor). Mantenha pain.008.001.02 apenas se o banco ainda o pedir.
- Lançamento agrupado: um único crédito por ficheiro no extrato, ou um crédito por cobrança.
- Enviar o primeiro débito de uma autorização como FRST: o rulebook admite RCUR desde o primeiro débito; mantenha FRST se o banco ainda o exigir.
- Enviar o último débito de um plano limitado como FNAL: opcional. Após um débito FNAL, o mandato fica encerrado e não pode voltar a ser usado.
- Incluir sempre a morada do devedor no ficheiro: a morada é sempre enviada para contas fora do EEE; ative a opção se o banco a pedir em cada débito.
- Gerar o ficheiro bancário automaticamente: a tarefa diária cria o ficheiro das cobranças com vencimento em N dias e envia um aviso para o endereço de alertas. O ficheiro em si nunca é enviado por e-mail: é descarregado no back office.
- Marcar como paga automaticamente após N dias sem rejeição (5 por predefinição). 0 para confirmar manualmente ou com camt.054.
Rejeições
- Códigos de motivo com nova tentativa automática: AM04 e MS03 por predefinição.
- Número máximo de novas tentativas e prazo antes de uma nova tentativa.
- Custo de rejeição acrescentado à nova tentativa, apenas se as suas condições de venda o previrem.
- Códigos de motivo que revogam a autorização: AC01, AC04, AC06, AC13, MD01 e MD07 por predefinição. O mandato é encerrado e os seus planos são cancelados.
- Email para alertas ao comerciante: rejeições, revogações, mudanças de banco, planos suspensos e ficheiros automáticos. E-mail da loja se ficar vazio.
Dados e privacidade
- Conservar as autorizações encerradas após o último débito: no mínimo 13 meses (ver RGPD abaixo).
- Eliminar todos os dados na desinstalação: desativado por predefinição. Os mandatos são provas; eliminá-los pode violar as suas obrigações de conservação.
Percurso do cliente
Assinatura no checkout
No passo de pagamento, o cliente escolhe o débito direto SEPA. O bloco mostra o montante e a data do débito. Se já tiver um mandato ativo, seleciona a sua conta (IBAN oculto) e confirma a encomenda.
Caso contrário, assina um novo mandato em 3 passos dentro do bloco de pagamento. O formulário é pré-preenchido com a morada de faturação: empresa, titular, morada, local de assinatura (a localidade), IBAN e BIC. O IBAN é formatado e verificado durante a escrita: comprimento do país, dígitos de controlo, BIC obrigatório fora do EEE. O cliente lê o texto do mandato (expansível) e assinala a aceitação. Em B2B, confirma também que a conta é profissional e que vai registar o mandato no seu banco.

Recebe por e-mail um código de 6 algarismos válido durante 10 minutos. Pode pedir um novo código após 45 segundos; após 5 erros, tem de pedir outro. O mandato fica assinado logo que o código correto é introduzido. Até lá, a confirmação da encomenda fica bloqueada com uma mensagem.


A página de confirmação recorda o montante, a data do débito, o IBAN oculto, a referência do mandato e o identificador de credor.

Se o tema impedir a execução do script, após a confirmação o cliente é redirecionado para a página de assinatura autónoma e depois a encomenda é criada. Não é possível criar duas vezes uma encomenda para o mesmo carrinho, e o montante é sempre recalculado no servidor a partir do carrinho.
E-mail de confirmação e PDF do mandato
O cliente recebe a confirmação do mandato com o IBAN oculto e uma ligação para os seus mandatos. Se a opção estiver ativa, a cópia PDF anexada também tem o IBAN oculto.

O PDF inclui as menções do mandato SEPA: título «SEPA Business to Business Direct Debit Mandate» em B2B ou «SEPA Direct Debit Mandate» em Core, referência única, identificador e morada do credor, devedor, conta, tipo de pagamento (recorrente ou pontual), texto de autorização, local e data da assinatura, método de assinatura e impressão SHA-256.

Página de assinatura autónoma
Quando envia um pedido de assinatura a partir do back office, o cliente recebe uma ligação segura para uma página de assinatura, sem necessidade de iniciar sessão. A página mostra o resumo do credor e os mesmos controlos do checkout.

Conta do cliente
A página As minhas autorizações SEPA apresenta cada mandato num cartão: PDF, planos em curso e últimas cobranças. O cliente pode revogar um mandato ou clicar em Alterar a conta bancária: assina um novo mandato, os seus planos e cobranças ainda não enviadas passam para a nova conta e o mandato antigo é encerrado. A ligação só aparece em A minha conta para os clientes dos grupos autorizados ou que já têm um mandato. O detalhe de cada encomenda mostra a data do débito e o seu estado.

Back office
Painel
Montante a enviar ao banco nos próximos 7 dias, montante no banco a aguardar confirmação, cobrado no mês, taxa de rejeição a 90 dias, receita recorrente mensal dos planos de montante fixo, mandatos ativos e pendentes. Um gráfico mostra as 6 próximas semanas (cobranças criadas e previsão dos planos). As últimas rejeições e os mandatos a aguardar assinatura, com um botão Relembrar, completam a página. É apresentado um alerta se a tarefa diária não tiver sido executada nas últimas 36 horas.

Mandatos
A lista mostra a referência, o devedor, o IBAN oculto, o esquema (B2B ou Core), o tipo (recorrente ou pontual) e o estado. O botão Nova autorização oferece dois modos: enviar ao cliente um pedido de assinatura online ou registar um mandato em papel já assinado, com o local e a data da assinatura. O campo Substitui a autorização transfere os planos de um mandato existente quando o novo é assinado.

A ficha de um mandato mostra as provas de assinatura (data, método, local, endereço IP, navegador, impressão da prova), o PDF selado com o seu SHA-256, os planos, as cobranças e o histórico de auditoria cronológico com o controlo de integridade. O botão Mostrar o IBAN completo exige a permissão de edição e cada visualização fica registada. A ficha de cliente do back office apresenta também um bloco Autorizações SEPA com o botão Pedir uma nova autorização.

Cobranças
Lista filtrável de todas as cobranças com o seu estado: a exportar, enviada ao banco, paga, rejeitada, cancelada. Na ficha de uma cobrança: marcar como paga, registar uma rejeição com o seu código, cancelar (antes da exportação). Após uma rejeição com um código de nova tentativa, a ficha mostra a nova tentativa agendada e o histórico. O botão Nova cobrança pontual cria uma cobrança num mandato ativo, associada ou não a uma encomenda. Um montante nulo é recusado e um mandato pontual só aceita uma cobrança.

Planos recorrentes
Um plano está associado a um mandato recorrente (ativo ou a aguardar assinatura) e funciona em dois modos: montante fixo ou repetir uma encomenda (a encomenda de referência é repetida aos preços do dia em cada vencimento e depois cobrada). Escolha a frequência, o próximo vencimento e o número de cobranças (0 para sem fim). O cliente recebe um e-mail de resumo. Um plano pode ser suspenso, retomado ou terminado.
Ficheiros bancários
- Escolha a data limite das cobranças a incluir e clique em Pré-visualizar: nada é exportado. A pré-visualização mostra um bloco de pagamento por esquema, sequência (FRST, RCUR, OOFF, FNAL) e data, e as datas antecipadas para respeitar o prazo do banco.
- Clique em Gerar. O ficheiro é validado com o esquema oficial ISO 20022 antes de ser guardado e depois armazenado cifrado com a sua impressão SHA-256. A lista indica o resultado da validação e o número de transferências.
- Descarregue o ficheiro e carregue-o no próprio dia no portal do banco. O módulo nunca envia nada a um banco.
- Importe depois os ficheiros de retorno: pain.002 (ficheiro ou operações rejeitados), camt.054 ou camt.053 (devoluções e créditos). Um mesmo ficheiro importado duas vezes não volta a ser processado.

Um ficheiro ainda não enviado pode ser cancelado: as suas cobranças voltam a «a exportar». A geração está bloqueada: dois cliques, dois funcionários ou uma tarefa diária simultânea não conseguem exportar duas vezes as mesmas cobranças.
Página da encomenda
A página da encomenda no back office mostra um bloco de débito SEPA: mandato, IBAN oculto, montante, vencimento e estado de cada cobrança.

Ciclo de uma cobrança
- A exportar: criada com a encomenda, por um plano ou manualmente. O cliente recebe a pré-notificação. A encomenda fica em «Débito direto SEPA agendado».
- Enviada ao banco: incluída num ficheiro. A data pode ser adiada para o primeiro dia possível segundo o calendário TARGET e o prazo de entrega.
- Paga: após o prazo sem rejeição, na importação de um camt.054 ou manualmente. A encomenda passa a «Pagamento aceite».
- Rejeitada: código de motivo registado, encomenda em «Débito direto SEPA rejeitado», nova tentativa ou revogação conforme a configuração.
Sequências
- FRST: primeiro débito de um mandato recorrente, se a opção estiver ativa. Um só primeiro débito por mandato e por ficheiro; se for rejeitado, a tentativa seguinte volta a sair como FRST.
- RCUR: débitos seguintes de um mandato recorrente.
- OOFF: débito único de um mandato pontual. Uma nova tentativa após rejeição é tratada como o mesmo pagamento; se necessário, confirme esta prática com o seu banco.
- FNAL: último débito de um plano limitado, se a opção estiver ativa. O mandato é encerrado após o pagamento.
Um mandato que não tenha sido usado em nenhuma cobrança durante 36 meses caduca.
Gestão das rejeições
| Código | Significado | Ação predefinida |
|---|---|---|
| AM04 | Saldo insuficiente | Nova tentativa |
| MS03 | Motivo não indicado pelo banco | Nova tentativa |
| AC01, AC04, AC06 | Conta incorreta, encerrada ou bloqueada | Revogação do mandato |
| AC13 | Conta de consumidor em B2B | Revogação do mandato |
| MD01 | Sem mandato válido (muitas vezes um mandato B2B não registado no banco) | Revogação do mandato |
| MD07 | Devedor falecido | Revogação do mandato |
| MS02, MD06 | Recusa ou reembolso pedido pelo devedor | Alerta, tratamento manual |
Uma rejeição do ficheiro ou de um bloco de pagamento num pain.002 (formato, identificador de credor não reconhecido…) não diz respeito ao cliente: as cobranças voltam a «a exportar» para o ficheiro seguinte.
Prova de assinatura e histórico de auditoria
- Instantâneo de prova: no momento da assinatura, o módulo regista um instantâneo com data e hora que contém o texto exato do mandato e a sua impressão, o esquema, o tipo de pagamento, o local, o endereço IP, o navegador, o método de assinatura, o IBAN oculto e a sua impressão. O IBAN completo nunca figura nele.
- PDF selado: o PDF do mandato é produzido uma única vez, na assinatura, e depois armazenado cifrado. O seu SHA-256 fica registado no mandato e no histórico de auditoria; as transferências seguintes devolvem exatamente esse ficheiro.
- Histórico de auditoria: criação, envio e erros de código, assinatura, PDF selado, e-mails, visualizações do IBAN completo, transferências, cobranças, exportações, pagamentos, rejeições, revogação e anonimização. Os eventos de cada mandato são encadeados com SHA-256: uma linha alterada ou eliminada é assinalada na ficha do mandato.
O código de utilização única enviado por e-mail é uma assinatura eletrónica na aceção do artigo 3.º, ponto 10, do Regulamento eIDAS (UE) n.º 910/2014; não é uma assinatura qualificada. O módulo não garante nenhum valor jurídico particular: o seu valor probatório e a sua aceitação pelo banco devem ser avaliados por si e pelos seus consultores.
Segurança e permissões dos funcionários
- IBAN dos mandatos e ficheiros bancários cifrados com AES-256-GCM, com uma chave derivada da chave secreta da loja (ficheiro de parâmetros, não a base de dados). Guarde este ficheiro numa migração: sem ele, os IBAN e os ficheiros deixam de ser legíveis.
- Os duplicados são detetados com uma impressão HMAC-SHA256, nunca com o IBAN em claro.
- Descarregar um ficheiro bancário ou o PDF completo, mostrar o IBAN completo, reenviar uma ligação de assinatura ou executar as tarefas exige a permissão de edição no separador correspondente. Um perfil só de leitura obtém uma cópia do PDF com o IBAN oculto e não pode descarregar ficheiros bancários.
- Em multiloja, um funcionário só vê os mandatos, cobranças, planos e ficheiros das lojas do seu contexto.
- Na loja, um mandato só está acessível ao seu titular, na sua loja, com um token contra a falsificação de pedidos na revogação e no PDF.
- Os ficheiros de retorno importados são lidos sem entidades externas (proteção XXE).
Tarefa diária (cron)
O URL de cron, protegido por um token, cria as cobranças dos planos que vencem dentro do prazo de pré-notificação, gera o ficheiro automático se estiver ativado, marca como pagas as cobranças sem rejeição após o prazo configurado, faz caducar os mandatos sem utilização há 36 meses e elimina as assinaturas abandonadas há 60 dias. Duas execuções simultâneas não se sobrepõem. O botão Executar as tarefas agora da página Ficheiros bancários faz o mesmo para a loja atual.
E-mails enviados
- Ao cliente: código de assinatura, confirmação do mandato, pedido de assinatura, aviso de plano, pré-notificação da cobrança, rejeição.
- Ao comerciante: rejeição, revogação pelo cliente, mudança de banco, plano suspenso, ficheiro automático pronto (com a ligação para o back office, sem ficheiro anexado).
Os 8 modelos são fornecidos em 8 línguas, em HTML e texto, em mails/, e editam-se como os e-mails nativos. Nenhum e-mail contém um IBAN completo nem um ficheiro bancário.
Fatura, ficha da encomenda e RGPD
A fatura PDF inclui uma menção de pré-notificação (montante, data, IBAN oculto, referência do mandato, identificador de credor), que passa a «pago em» quando a cobrança é confirmada.
Com o módulo RGPD oficial, os mandatos (IBAN oculto) e as cobranças são incluídos na exportação de dados. Num pedido de apagamento, só são anonimizados os mandatos pendentes e os mandatos encerrados cujo último débito ultrapassa o prazo de conservação configurado: o IBAN, o e-mail, a morada e o PDF selado são então eliminados. Os restantes mandatos são conservados como prova e recebe um alerta.
Prazo de conservação: os rulebooks do EPC remetem para o direito nacional e impõem, no mínimo, o período de reembolso de uma operação não autorizada, ou seja, 13 meses após a data do débito. O direito nacional, em especial o contabilístico, pode exigir mais: defina-o com os seus consultores. O módulo não fixa nenhum prazo nacional e recusa um valor inferior a 13 meses.
Limites
- O módulo produz ficheiros pain.008 e lê ficheiros pain.002, camt.054 e camt.053. Não transmite nada a um banco nem oferece ligação EBICS ou prestador de pagamentos.
- Não garante a conformidade legal da sua utilização: confirme com o banco o formato, os prazos, o BIC, a morada e o uso de FRST, e com os seus consultores as condições de venda, o prazo de pré-notificação e o prazo de conservação.
- Só são considerados os feriados TARGET comuns: 1 de janeiro, Sexta-feira Santa, Segunda-feira de Páscoa, 1 de maio, 25 e 26 de dezembro.
- Os países recentemente acrescentados pelo EPC (Albânia, Moldávia, Montenegro, Macedónia do Norte, Sérvia) são aceites com BIC obrigatório; a participação efetiva de cada banco não é verificada.
Resolução de problemas
O meio de pagamento não aparece
Verifique o assistente de arranque (credor completo com a morada), se o carrinho está em euros, se o cliente tem sessão iniciada (não é visitante), se a morada de faturação tem uma empresa quando a opção está ativa, se o cliente pertence a um grupo autorizado e se não ultrapassou a exposição ou o número de rejeições permitidos.
Rejeição MD01 num mandato B2B
O cliente não registou o mandato no seu banco. Peça-lhe que o faça com a referência do mandato e o seu identificador de credor e crie depois uma nova cobrança pontual.
O cliente não recebe o código
Verifique a configuração de e-mail do PrestaShop e a pasta de spam do cliente. Pode ser pedido um novo código após 45 segundos; é válido durante 10 minutos.
O banco recusa o ficheiro
Verifique o formato esperado (pain.008.001.08 ou .02), o BIC e a morada do devedor. Um ficheiro que não respeite o esquema ISO 20022 nunca é guardado: a mensagem apresentada na geração cita os primeiros erros. Se a coluna do esquema indicar «Não verificado», faltam no servidor as extensões PHP DOM ou libxml.
«Histórico de auditoria alterado»
Uma linha do histórico de auditoria do mandato foi alterada ou eliminada diretamente na base de dados. A mensagem indica o evento a partir do qual a cadeia deixou de estar intacta. Restaure a tabela a partir de uma cópia de segurança.