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 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.

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.

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.

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.

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

• 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.