# Custos de Pagamento (dfpaymentfees): guia completo > Apresentação O DataFirefly Custos de Pagamento permite aplicar custos adicionais a cada meio de pagamento da sua loja PrestaShop 8 ou 9. O objetivo é duplo: repercutir o custo real… - Página: - Idioma: pt - Atualizado em: 2026-09-03 - Outros idiomas: [fr](https://www.datafirefly.com/documentation/dfpaymentfees/index.md), [en](https://www.datafirefly.com/en/documentation/dfpaymentfees/index.md), [es](https://www.datafirefly.com/es/documentation/dfpaymentfees/index.md), [de](https://www.datafirefly.com/de/documentation/dfpaymentfees/index.md), [it](https://www.datafirefly.com/it/documentation/dfpaymentfees/index.md), [pl](https://www.datafirefly.com/pl/documentation/dfpaymentfees/index.md), [nl](https://www.datafirefly.com/nl/documentation/dfpaymentfees/index.md) - Índice: ## Apresentação O DataFirefly Custos de Pagamento permite aplicar custos adicionais a cada meio de pagamento da sua loja PrestaShop 8 ou 9. O objetivo é duplo: repercutir o custo real de um modo de pagamento (comissões, gestão do pagamento à cobrança, processamento de cheques ou transferências) e orientar os seus clientes para os meios de pagamento mais vantajosos para a sua loja. O módulo assenta num motor de regras: cada regra combina um montante fixo e/ou uma percentagem, uma base de cálculo, limites, um limiar de gratuitidade e um conjunto de condições (grupo de clientes, país, moeda, montante do carrinho). Os custos são apresentados ao cliente durante o funil de encomenda e depois acrescentados automaticamente à encomenda na sua validação. **Quadro legal em Portugal e na UE.** A diretiva PSD2, transposta pelo Decreto-Lei n.º 91/2018, proíbe cobrar custos adicionais aos consumidores pela utilização de cartões de débito e de crédito abrangidos pelo regulamento das comissões de intercâmbio (a quase totalidade dos cartões Visa/Mastercard de consumidores da UE), bem como das transferências e débitos diretos SEPA. Reserve as regras de custos aos meios não abrangidos: pagamento à cobrança, cheque, referência Multibanco ou MB WAY consoante o enquadramento do seu PSP, ou aos clientes B2B. Em caso de dúvida, consulte o Banco de Portugal ou um jurista. ## Instalação 1. No seu back-office PrestaShop, vá a **Módulos → Gestor de módulos → Instalar um módulo**. 2. Selecione o ficheiro `dfpaymentfees.zip` descarregado a partir da sua conta DataFirefly. 3. Clique em **Instalar** e depois em **Configurar**. 4. Limpe a cache do PrestaShop (**Parâmetros avançados → Desempenho → Limpar a cache**). 5. A partir da página de configuração, clique em **Gerir as regras de custos** para criar a sua primeira regra. O módulo é compatível com PrestaShop 8.0 → 9.x e testado em PHP 8.1 a 8.3. Não é necessária nenhuma alteração do tema. A desinstalação elimina as tabelas do módulo e o separador de administração. ## Parâmetros gerais A página de configuração do módulo (**Módulos → Gestor de módulos → Custos de Pagamento → Configurar**) contém duas definições globais: - **Mostrar os custos no checkout**: mostra o montante dos custos ao lado de cada meio de pagamento durante a encomenda. Desative esta opção se preferir aplicar os custos apenas no momento da validação, sem os anunciar na lista dos meios de pagamento. - **Designação dos custos**: designação por defeito apresentada ao cliente e na encomenda (por exemplo « Custos de pagamento »). Este campo é multilingue e pode ser sobreposto regra a regra. ## Criar uma regra de custos A partir de **Gerir as regras de custos**, clique em **Adicionar uma regra de custos**. O formulário está organizado em quatro blocos: identificação, montante, limites e condições. ### Identificação - **Ativa**: ativa ou desativa a regra sem a eliminar. - **Designação (cliente)**: o texto apresentado ao cliente no checkout e na encomenda. Campo multilingue e obrigatório. - **Meio de pagamento**: o módulo em causa (por exemplo `ps_wirepayment`, `ps_checkpayment`, o seu módulo de cartão…), ou **Todos os meios de pagamento** para uma regra genérica. - **Prioridade**: um inteiro. Um valor mais baixo é avaliado primeiro. Ver a secção « Ordem de avaliação » abaixo. ### Montante dos custos - **Custo fixo**: um montante fixo acrescentado (por exemplo `1.50`). - **Custo em percentagem**: uma percentagem aplicada à base de cálculo (por exemplo `2.5` para 2,5 %). - **Incluir os portes na base %**: se ativado, a percentagem incide sobre os produtos _e_ os portes; caso contrário, apenas sobre os produtos. - **Base de cálculo com IVA**: escolha se a percentagem é calculada sobre o total com IVA ou sobre o total sem IVA. Os dois montantes são cumuláveis. A fórmula aplicada é: ``` custos = custo_fixo + (base × custo_percentagem / 100) ``` ### Limites e gratuitidade - **Custo mínimo**: se o cálculo der um montante inferior, é aplicado este mínimo. `0` = sem mínimo. - **Custo máximo**: limita o montante dos custos. `0` = sem máximo. - **Limiar de gratuitidade**: se o total com IVA do carrinho atingir este montante, não é aplicado nenhum custo. `0` = desativado. O limiar de gratuitidade é uma excelente alavanca de valor médio do carrinho: « Custos de pagamento oferecidos a partir de 150 € de compras » incentiva o cliente a completar a sua encomenda. ## Condições de aplicação Quatro famílias de condições permitem visar precisamente quando a regra se aplica. Uma lista deixada vazia significa « nenhuma restrição » nesse critério. - **Grupos de clientes**: a regra só se aplica se o cliente pertencer a um dos grupos selecionados. Tipicamente: aplicar os custos aos particulares e isentar os profissionais (ou o inverso, tendo em conta o quadro legal acima). - **Países**: baseado no _país da morada de faturação_ do carrinho. - **Moedas**: a regra só se aplica às moedas selecionadas. - **Montante mínimo / máximo do carrinho**: a regra só se aplica se o total com IVA do carrinho estiver neste intervalo. `0` desativa o limite em causa. Em multiloja, um campo **Lojas** adicional permite associar a regra a uma ou várias lojas. Deixar vazio associa a regra a todas as lojas. ## Ordem de avaliação das regras Para um dado meio de pagamento, o módulo recupera todas as regras ativas que visam esse módulo (ou « Todos »), ordenadas por prioridade crescente e depois por identificador. Avalia as condições de cada regra por essa ordem e **aplica a primeira regra cujas condições estão todas satisfeitas**. As regras seguintes são ignoradas. Consequência prática: coloque as suas regras mais específicas (por exemplo « pagamento à cobrança, Portugal, particulares ») em prioridade baixa (0, 10, 20…) e as suas regras genéricas (« todos os meios de pagamento ») em prioridade alta (100), para que só sirvam de recurso. Caso particular do limiar de gratuitidade: se uma regra corresponder mas o carrinho atingir o seu limiar de gratuitidade, não é aplicado nenhum custo, e o módulo não avalia as regras seguintes. A gratuitidade é portanto uma decisão final, não uma simples « passagem à regra seguinte ». ## Gestão do IVA Duas definições determinam o tratamento fiscal dos custos: - **Montantes introduzidos com IVA**: indique se os montantes que preencheu (custo fixo, limites) já incluem o IVA ou não. - **Regra de imposto**: a regra de imposto PrestaShop aplicada aos custos. Selecione **Sem imposto** para custos sem IVA. O módulo calcula a taxa aplicável a partir da regra de imposto e da morada de faturação do cliente, e deduz depois a repartição: - Se os montantes forem introduzidos **com IVA**: `sem IVA = com IVA / (1 + taxa)`. - Se os montantes forem introduzidos **sem IVA**: `com IVA = sem IVA × (1 + taxa)`. Os dois valores, bem como a taxa aplicada, são registados na encomenda para a sua contabilidade. ### Exemplo de cálculo Regra: custo fixo 1,00 € + 2 % do carrinho, base com IVA produtos + portes, limite máx. 5,00 €, montantes introduzidos com IVA, IVA 23 %. - Carrinho: 120,00 € com IVA de produtos + 5,00 € com IVA de portes = base 125,00 €. - Custos brutos: 1,00 + (125,00 × 2 / 100) = **3,50 € com IVA**. - Abaixo do limite de 5,00 €: conservado tal como está. - Repartição: sem IVA = 3,50 / 1,23 = **2,85 €**, IVA = **0,65 €**. ## Apresentação do lado do cliente Quando a opção **Mostrar os custos no checkout** está ativada, o módulo calcula os custos para cada meio de pagamento disponível e transmite-os ao front-office. Na página `/order`: - O montante dos custos é acrescentado ao lado da designação de cada meio de pagamento em causa. - Um lembrete aparece sob a lista dos meios de pagamento para a opção atualmente selecionada, e atualiza-se em tempo real quando o cliente muda de meio de pagamento. A apresentação é puramente informativa: o montante realmente faturado é recalculado do lado do servidor na validação da encomenda. ## Aplicação na encomenda Na validação da encomenda (hook `actionValidateOrder`), o módulo recalcula os custos para o meio de pagamento efetivamente usado e depois: 1. Atualiza os totais da encomenda (`total_paid`, `total_paid_tax_incl`, `total_paid_tax_excl` e `total_paid_real` se for o caso). 2. Atualiza os totais da fatura se já existir uma fatura. 3. Atualiza o montante do pagamento registado, para se manter coerente com o montante cobrado. 4. Regista a linha de custos (designação, sem IVA, com IVA, taxa) na tabela `df_payment_fee_order`. A linha de custos é depois apresentada na página de confirmação de encomenda, no detalhe da encomenda do lado do cliente, na página de encomenda do back-office, e acrescentada ao e-mail de confirmação. Uma proteção impede o duplo processamento: se uma encomenda já tiver uma linha de custos, o módulo não faz nada. ## Compatibilidade com as gateways de pagamento **Ponto importante a compreender antes da passagem a produção.** O PrestaShop não fornece nenhum hook nativo que permita injetar custos próprios de um meio de pagamento _no total do carrinho antes_ da chamada à gateway. Os custos são portanto apresentados ao cliente no checkout e depois registados na encomenda depois da sua criação. - **Pagamentos offline** (transferência, cheque, pagamento à cobrança, pagamento em loja): o funcionamento é completo e sem reservas. O cliente vê os custos, a encomenda e a fatura incluem-nos, e cobra o montante total apresentado. - **Gateways com redirecionamento ou incorporadas** (PayPal, Stripe, IfthenPay, Easypay, soluções bancárias): o montante transmitido à gateway é o calculado pelo módulo de pagamento a partir do carrinho. Consoante a sua gateway e a sua configuração, esse montante pode não incluir os custos. Verifique o comportamento em ambiente de teste antes da passagem a produção. Para estas últimas, duas abordagens são correntes: reservar as regras de custos aos meios de pagamento offline, ou capturar/ajustar o montante do lado da gateway. O nosso suporte pode aconselhá-lo consoante a gateway usada. ## Multiloja e multilingue **Multiloja**: cada regra é associada a uma ou várias lojas através do campo **Lojas** do formulário. Só as regras associadas à loja atual são avaliadas. Uma regra guardada sem seleção é associada a todas as lojas. **Multilingue**: a designação de cada regra é traduzível em todos os idiomas ativos da loja. Se a designação não estiver preenchida no idioma do cliente, o módulo usa a designação global definida nos parâmetros do módulo. ## Resolução de problemas ### Os custos não aparecem no checkout - Verifique que a opção **Mostrar os custos no checkout** está ativada nos parâmetros do módulo. - Verifique que a regra está **ativa** e que visa o meio de pagamento em causa (ou « Todos »). - Verifique que o contexto do cliente satisfaz todas as condições: grupo, país de _faturação_, moeda, montante do carrinho. - Certifique-se de que o carrinho não atinge o limiar de gratuitidade da regra. - Limpe a cache do PrestaShop e faça um recarregamento forçado do navegador (Ctrl+F5) para purgar o JavaScript antigo. ### Os custos aparecem mas não são acrescentados à encomenda O cálculo no checkout e o cálculo na validação usam o nome técnico do módulo de pagamento. Se o seu módulo de pagamento registar uma designação diferente do nome técnico, verifique na tabela `df_payment_fee_order` que foi criada uma linha para a encomenda. Se não for o caso, crie uma regra que vise **Todos os meios de pagamento** para validar o funcionamento, e contacte depois o suporte com o nome do módulo de pagamento usado. ### Uma regra nunca se aplica apesar de parecer correta Uma regra mais prioritária (valor de prioridade mais baixo) corresponde provavelmente em primeiro lugar. Lembre-se de que só a primeira regra correspondente é aplicada. Aumente a prioridade das regras genéricas ou afine as condições das regras concorrentes. ### O montante de IVA parece incorreto Verifique a coerência entre a definição **Montantes introduzidos com IVA** e os valores que preencheu. Um montante introduzido com IVA quando a definição indica sem IVA (ou o inverso) desloca a repartição. Verifique também que a regra de imposto selecionada se aplica ao país de faturação do cliente. ### O checkout está lento ou bloqueia Certifique-se de que usa a versão 1.0.0 ou superior do módulo, limpe a cache do PrestaShop e force o recarregamento do navegador (Ctrl+F5) para eliminar uma versão de JavaScript em cache. ## Desinstalação Desinstale o módulo a partir do Gestor de módulos. A desinstalação elimina o separador de administração, as variáveis de configuração e todas as tabelas do módulo, incluindo o histórico dos custos aplicados às encomendas. Os totais já registados nas encomendas existentes não são modificados. Se quiser conservar o histórico dos custos para fins contabilísticos, exporte a tabela `df_payment_fee_order` antes de desinstalar o módulo.