DataFirefly Subscriptions: guia completo (PrestaShop 8 e 9)

Apresentação

O DataFirefly Subscriptions transforma a sua loja PrestaShop 8 ou 9 numa máquina de receitas recorrentes. O módulo assenta numa arquitetura «card on file»: o cliente paga uma única vez no checkout através de uma opção de pagamento nativa, o seu cartão é registado de forma segura no Stripe, e depois um cron diário debita automaticamente o cartão a cada vencimento e cria uma verdadeira encomenda PrestaShop no montante exato, portes incluídos.

Pontos-chave da arquitetura:

• Um único motor de faturação: nenhum objeto Subscription do lado do Stripe, tudo é comandado pela sua loja. Os débitos duplos são estruturalmente impossíveis.
• Montantes exatos: cada renovação reconstrói um carrinho real e calcula o total através do motor de preços do PrestaShop (descontos, impostos, portes).
• 3DS/SCA gerido: a autenticação forte é gerida no pagamento inicial; as renovações usam o mecanismo off-session conforme à SCA.
• Nenhum dado bancário do lado do PrestaShop: a conformidade PCI-DSS é assegurada pelo Stripe.

Instalação

1. Transfira o ZIP do módulo a partir da sua conta de cliente DataFirefly.
2. No seu back-office PrestaShop: Módulos → Gestor de módulos → Instalar um módulo, e selecione o ZIP.
3. O módulo cria automaticamente as suas tabelas, os seus separadores de administração (Subscrições, Planos, Registos, Painel) e regista os seus hooks.
4. Clique em Configurar para abrir a página de configuração.

Configuração Stripe

Chaves API

Na configuração do módulo, preencha as suas chaves Stripe. O módulo gere dois conjuntos de chaves distintos:

• Modo de teste: chave pública pk_test_... e chave secreta sk_test_..., para validar o percurso completo sem débito real (cartão de teste 4242 4242 4242 4242).
• Modo live: chave pública pk_live_... e chave secreta sk_live_..., para a produção.

Encontra estas chaves no seu painel Stripe: Programadores → Chaves API. Alterne entre teste e live com o interruptor «Modo» do módulo.

Webhook

O webhook serve apenas para os eventos excecionais (a faturação é comandada pelo cron, não pelo Stripe). No seu painel Stripe: Programadores → Webhooks → Adicionar um endpoint, com o URL apresentado na configuração do módulo (no formato https://asualoja.pt/module/dfsubscription/webhook), e subscreva estes três eventos:

• payment_method.detached: cartão eliminado do lado do Stripe: a subscrição passa a «pagamento falhado» para o avisar antes do vencimento.
• charge.dispute.created: litígio (chargeback): registado na subscrição em causa.
• charge.refunded: reembolso: registado na subscrição em causa.

Copie depois o segredo de assinatura (whsec_...) fornecido pelo Stripe para o campo correspondente da configuração.

Configuração do cron

O cron é o motor das renovações: deteta todos os dias as subscrições que chegaram ao vencimento, debita os cartões registados e cria as encomendas. O URL protegido por token é apresentado na configuração e no painel do módulo, no formato:

https://asualoja.pt/module/dfsubscription/cron?token=O_SEU_TOKEN

Crie uma tarefa cron diária no seu alojamento (cPanel, Plesk, crontab) que chame este URL. Exemplo de crontab para uma execução todos os dias às 6h00:

0 6 * * * curl -s "https://asualoja.pt/module/dfsubscription/cron?token=O_SEU_TOKEN" > /dev/null 2>&1

Criar planos de subscrição

Os planos são geridos diretamente a partir da página de produto do back-office: Catálogo → Produtos → o seu produto → separador Módulos / DataFirefly Subscriptions. Para cada plano, defina:

• Frequência de faturação: semanal, quinzenal, mensal, trimestral, semestral ou anual.
• Frequência de entrega: idêntica à faturação, semanal, quinzenal ou mensal. Exemplo: faturação mensal + entrega semanal = box semanal com pagamento mensal.
• Desconto (%): a redução concedida aos subscritores em relação ao preço de compra única. É apresentado na página de produto e aplica-se também a cada renovação.
• Permanência mínima: número de ciclos antes de a resiliação ser possível (0 = resiliação livre).
• Ciclos máximos: para subscrições de duração limitada (0 = ilimitado).
• Dias de teste: período de experiência antes da primeira faturação.

Um produto pode propor vários planos (ex.: mensal -10% e anual -20%): o cliente escolhe no bloco «Subscreva e poupe» da página de produto.

Percurso do cliente

Página de produto

Um bloco expansível apresenta os planos disponíveis com os seus preços com desconto. O cliente seleciona o seu plano (a seleção é registada na base de dados, fiável mesmo que mude de dispositivo), e adiciona depois ao carrinho normalmente.

Checkout e pagamento

Na etapa de pagamento, a opção «Pagar com cartão e ativar a minha subscrição» aparece se o carrinho contiver apenas produtos em subscrição e o cliente tiver sessão iniciada. O formulário de cartão seguro do Stripe é apresentado diretamente na página:

1. O cliente introduz o seu cartão; o 3D Secure dispara automaticamente se o seu banco o exigir.
2. O pagamento cobre o total exato do carrinho, portes incluídos.
3. O cartão é registado no Stripe para os ciclos seguintes (card on file, com consentimento conforme à SCA).
4. O módulo volta a verificar do lado do servidor o estado e o montante do pagamento antes de criar a encomenda: nunca se confia apenas na palavra do navegador.

Renovações

A cada execução do cron, para cada subscrição que chegou ao vencimento:

1. O módulo reconstrói um verdadeiro carrinho PrestaShop: produto, combinação, morada e transportadora de origem.
2. O desconto do plano é aplicado através de uma regra de carrinho automática de uso único.
3. O total exato é calculado pelo motor de preços nativo: impostos e portes incluídos se a opção «Portes nas renovações» estiver ativa (está por defeito).
4. O cartão registado é debitado fora de sessão precisamente por esse montante.
5. É criada uma encomenda PrestaShop padrão, com o estado de encomenda à sua escolha (configurável, ex.: um estado dedicado «Renovação»).
6. O cliente recebe o e-mail de confirmação de renovação; o evento é registado.

Cada encomenda de renovação é visível em Encomendas como qualquer venda, com a sua transação Stripe associada: as suas exportações contabilísticas e a sua gestão de stock funcionam sem alteração.

Dunning: gestão das falhas de pagamento

Quando um débito de renovação falha (cartão expirado, plafond, recusa bancária):

1. A subscrição passa ao estado «pagamento falhado» e o cliente recebe imediatamente um e-mail de lembrete a convidá-lo a atualizar o seu cartão.
2. O cron tenta de novo automaticamente o pagamento: por defeito 3 tentativas com 3 dias de intervalo, sendo os dois valores configuráveis.
3. Após o número de falhas consecutivas configurado, a subscrição é anulada automaticamente e o cliente é informado.

Cada tentativa e o seu resultado são registados nos logs da subscrição. Na prática, o dunning recupera 50 a 70% dos pagamentos que teriam sido perdidos numa falha seca.

Área de cliente «As minhas subscrições»

Acessível a partir da conta de cliente, esta área lista as subscrições com o seu estado, a próxima data de faturação e de entrega. Consoante as suas definições, o cliente pode:

• Colocar em pausa / retomar: as datas são recalculadas na retoma.
• Saltar o próximo ciclo: a faturação e a entrega são adiadas em conjunto por um período.
• Resiliar: livremente, ou apenas após a permanência mínima do plano. Na resiliação, o cartão registado é automaticamente desassociado no Stripe e é enviado um e-mail de confirmação.

Cada ação pede uma confirmação e segue o padrão POST-redirect-GET: nenhuma submissão dupla possível, mensagens de confirmação nativas do PrestaShop.

Back-office

• Painel: MRR, subscrições ativas, taxa de churn, pagamentos falhados, URL de cron e de webhook prontos a copiar.
• Subscrições: lista filtrável por estado, frequência e cliente; vista detalhada com o histórico das encomendas geradas e os registos, e ligações diretas para a encomenda e a ficha de cliente.
• Planos: vista geral de todos os planos existentes (a criação é feita a partir da página de produto).
• Registos: todos os eventos com carimbo temporal: criações, renovações, falhas, lembretes, pausas, resiliações, webhooks recebidos.

FAQ técnica e resolução de problemas

A opção de pagamento não aparece no checkout

• Verifique que o carrinho contém apenas produtos com um plano selecionado e que o cliente tem sessão iniciada.
• Verifique que as chaves Stripe do modo ativo estão preenchidas.
• Se acabou de migrar a partir de uma versão 1.x: reinstale o módulo ou relance a atualização: as restrições de moedas/países/transportadoras são acrescentadas pelos scripts de migração 2.x e são indispensáveis à apresentação da opção.

As renovações não disparam

• Verifique que a tarefa cron está agendada e que o seu URL contém o token correto (teste o URL num navegador: deve responder com um resumo JSON).
• Consulte o separador Registos: cada execução do cron deixa aí um rasto.

Um pagamento 3DS fica «pendente»

Se o cliente fechar a página durante a autenticação 3D Secure, não ocorre nenhum débito e não é criada nenhuma encomenda. Pode simplesmente voltar a encomendar; o pagamento anterior expirará por si só do lado do Stripe.

Como testar o percurso completo?

1. Passe o módulo para modo de teste e preencha as chaves pk_test/sk_test.
2. Crie um plano num produto, faça uma encomenda com o cartão 4242 4242 4242 4242 (ou 4000 0027 6000 3184 para forçar um desafio 3DS).
3. Na base de dados, avance a data next_billing_date da subscrição para ontem, e chame depois o URL de cron: deve aparecer uma encomenda de renovação.
4. Para testar o dunning, use o cartão 4000 0000 0000 0341 (falha no débito off-session).