VibeFox Flutterwave for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.
Conta Flutterwave: você precisa das chaves secretas da sua conta Flutterwave, no painel da Flutterwave em Settings, API keys: FLWSECK_TEST-… para o modo de teste e FLWSECK-… para o modo de produção. Somente as chaves secretas são usadas. As chaves públicas e de criptografia não são necessárias. Você também configura um webhook com um hash secreto de sua escolha (veja Configuração).
Moedas: o carrinho é sempre cobrado na moeda do carrinho. O módulo não restringe países nem moedas por conta própria; a Flutterwave exibe um erro se a sua conta não aceitar a moeda. Você pode limitar moedas, países e grupos de clientes em Payment > Preferences.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No back office, vá em Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure, ou encontre depois o VibeFox Flutterwave Payment na lista de módulos e clique em Configure.
3. Informe a sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Informe as suas chaves secretas, configure o webhook no painel da Flutterwave e informe o mesmo hash secreto no módulo (veja Configuração).
5. Ative Enable/Disable e clique em Save. Teste um pagamento no modo de teste e depois ative o Live mode.
Ao instalar, o módulo cria dois status de pedido, Awaiting Flutterwave payment e Flutterwave payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Flutterwave Payment > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Live mode: real payments are accepted. ou Test mode: no real money is charged. Ela avisa quando a chave secreta do modo atual está vazia, quando o campo da chave de produção contém uma chave de teste (FLWSECK_TEST-…) no modo de produção, ou quando o campo da chave de teste contém uma chave de produção (FLWSECK-…) no modo de teste; nesses casos, o método de pagamento fica oculto na finalização de compra até que o problema seja corrigido. Ela também avisa quando nenhum hash secreto de webhook está definido: os webhooks são então rejeitados, e os pagamentos só são confirmados quando o cliente volta à sua loja. O título da primeira seção mostra o modo atual, TEST ou LIVE.
Flutterwave
Enable/Disable: Enable Flutterwave Payment liga ou desliga o método de pagamento. Padrão: desativado.
Title: o título do método de pagamento que os clientes veem na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Flutterwave. Obrigatório.
Description: o texto que os clientes veem abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Card, Bank Transfer, USSD, Mobile Money via Flutterwave.
Chaves de API
Copie as chaves secretas no painel da Flutterwave em Settings, API keys (a seção tem um link). O modo de teste e o modo de produção têm chaves diferentes.
Live mode: aceita pagamentos reais. Desative-o para o modo de teste. O modo de teste usa a chave secreta de teste e nenhum dinheiro real é cobrado. O modo de produção usa a chave secreta de produção. Padrão: desativado (modo de teste). Enquanto o modo de teste estiver ativo, os clientes veem TEST MODE - no real payments will be processed. abaixo do método de pagamento.
Test Secret Key: a sua chave secreta de teste da Flutterwave (FLWSECK_TEST-...).
Live Secret Key: a sua chave secreta de produção da Flutterwave (FLWSECK-...).
As chaves salvas e o hash secreto nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Webhook
O webhook confirma os pagamentos mesmo quando o cliente não volta à sua loja. No painel da Flutterwave, em Settings, Webhooks, informe a URL exibida em Webhook URL nesta seção e um hash secreto de sua escolha, tanto no modo de teste quanto no modo de produção. Com URLs amigáveis, a URL tem este formato: https://your-shop/module/wcp_flutterwave_payment/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram. O módulo reage a este evento:
Os outros eventos são ignorados.
Secret Hash: o hash secreto do webhook. Ele deve corresponder ao valor das configurações do webhook no seu painel da Flutterwave. A Flutterwave o envia com cada webhook, e o mesmo valor é usado para o modo de teste e o modo de produção. Webhooks sem um hash secreto válido são rejeitados. Sem o webhook, um pagamento só é confirmado quando o cliente volta à sua loja.
Clear saved secrets: marque Test Secret Key, Live Secret Key ou Secret Hash e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Pagamento
Payment Options: métodos de pagamento separados por vírgulas para exibir na página da Flutterwave, por exemplo card, banktransfer, ussd, mobilemoney. Deixe vazio para todos os métodos ativados na sua conta. A lista é organizada ao salvar (minúsculas, sem duplicados).
Autocomplete Orders: os pedidos pagos recebem o status Delivered em vez de Payment accepted, com uma única mudança de status. Padrão: desativado.
Avançado
Debug log: registra os eventos da API da Flutterwave para depuração em logs/flwv_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Chaves, o hash secreto e dados dos clientes nunca são registrados. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: remove as configurações e os logs do módulo quando ele é desinstalado. Os dados de pagamento salvos nos pedidos são sempre mantidos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Flutterwave) e confirma. É necessário um endereço de e-mail válido. O módulo cria um pagamento na Flutterwave para o total do carrinho na moeda do carrinho, com o e-mail do cliente, o telefone e o nome do endereço de cobrança, o nome e o logotipo da sua loja, e envia o cliente à página de pagamento da Flutterwave. Ali, o cliente paga com um dos métodos ativados na sua conta (ou listados em Payment Options). Neste ponto, ainda não existe nenhum pedido.
Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Flutterwave confirma: pelo webhook ou por uma verificação no servidor quando o cliente retorna. O pedido é então criado, e o cliente vê a página padrão de confirmação do pedido. Se o pagamento ainda estiver pendente, por exemplo uma transferência bancária, um pagamento USSD ou de dinheiro móvel, o pedido é criado em Awaiting Flutterwave payment e a página mostra Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Se o pedido foi colocado em espera para análise, por exemplo porque o valor pago não corresponde ao carrinho, a página mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed. Se um pagamento pendente falhar depois e o cliente abrir novamente a página de confirmação, ela mostra Your Flutterwave payment was not completed. Please contact us about this order.
Se a Flutterwave não puder ser acessada quando o cliente retornar, uma página Payment confirmation diz Your payment is being confirmed by Flutterwave. Your order will be created as soon as it is confirmed — please do not pay again. com os botões Check again e Back to checkout. O webhook cria o pedido assim que chegar.
Se o pagamento for recusado, o cliente volta à finalização de compra com Your payment was declined. You can try again or choose another payment method. Se o cliente cancelar na página da Flutterwave, a mensagem é Payment was cancelled. You can try again or choose another payment method. Se o pagamento não tiver sido concluído, a mensagem é The payment was not completed. You can try again or choose another payment method. O carrinho é mantido, e o cliente pode pagar novamente. Cada tentativa tem a sua própria referência, e um link de pagamento antigo pago depois continua sendo aceito.
Se a Flutterwave não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method. O motivo técnico é gravado no log.
Se o carrinho mudar entre o pagamento e a sua confirmação, por exemplo em outra aba do navegador, os valores deixam de corresponder e o pedido vai para Flutterwave payment on hold com uma nota.
O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo aceita apenas pagamentos avulsos. Não há finalização de compra incorporada ou em janela modal no seu site, cartões salvos, assinaturas, pagamentos divididos ou planos de pagamento. Links de pagamento hospedados não podem ser cancelados pela API da Flutterwave, por isso um link antigo de um carrinho ainda pode ser pago.
Pedidos e reembolsos
Status do pedido
Nenhum pedido ainda: o cliente foi enviado à Flutterwave e ainda não pagou, ou a Flutterwave ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted or Delivered: o pagamento foi confirmado. Delivered é usado quando Autocomplete Orders está ativado. O pagamento é registrado com a referência da Flutterwave (flw_ref) como ID da transação, e uma nota mostra o valor, o método de pagamento, a referência, a transação e o modo.
Awaiting Flutterwave payment: o cliente voltou enquanto o pagamento ainda estava pendente na Flutterwave. O pedido passa ao status pago quando a Flutterwave confirma o pagamento.
Flutterwave payment on hold: o valor ou a moeda verificados não correspondiam ao carrinho, ou o pagamento chegou depois que o pedido foi cancelado. O pagamento é registrado com o valor efetivamente pago (não com o valor cobrado pela Flutterwave em outra moeda). A nota explica o motivo. Processe o pedido ou reembolse o pagamento. Um pedido reembolsado ou cancelado nunca é reaberto por um webhook repetido.
Payment error: a Flutterwave informou que a última tentativa de pagamento de um pedido aguardando pagamento falhou ou foi cancelada. A nota mostra o motivo.
Canceled: definido por você. Se a Flutterwave informar depois um pagamento de um pedido cancelado, o pedido vai para Flutterwave payment on hold (veja acima).
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se for recebido um segundo pagamento para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse a duplicata no painel da Flutterwave.
Bloco Flutterwave payment
A página do pedido mostra um bloco Flutterwave payment com a referência (tx_ref), o ID da transação e a referência da Flutterwave, o modo, o status e o método de pagamento, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as Flutterwave notes do pedido.
Reembolsos
No bloco Flutterwave payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Flutterwave. Confirme a pergunta Refund this amount through Flutterwave? This cannot be undone. Reembolsos totais e parciais são aceitos. Você precisa da permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são feitos no valor e na moeda cobrados pela Flutterwave, então, após uma divergência de valor ou moeda, você pode reembolsar até o valor que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado com a chave secreta do modo em que o pagamento foi feito (teste ou produção), por isso essa chave precisa estar configurada. Se a Flutterwave recusar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID e o status do reembolso (completed, ou initiated com o status informado pela Flutterwave). Um reembolso total muda o pedido para Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que a Flutterwave confirma o pagamento.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Flutterwave.
Os reembolsos feitos no painel da Flutterwave não são sincronizados com o PrestaShop. Atualize o status do pedido manualmente, se necessário.
Chave de licença
O módulo funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença License — VibeFox Flutterwave Payment é o primeiro bloco em Modules > Module Manager > VibeFox Flutterwave Payment > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois, o bloco mostra a chave mascarada, o status (por exemplo, a data até a qual a licença está ativa e o seu domínio) e os botões Check now para verificar o status novamente, Change key para informar outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: presta-payment-flutterwave e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure para o módulo podem alterar a chave. Os textos do bloco seguem o idioma do back office (inglês e russo estão incluídos).
Se a chave não for aceita, o bloco informa o motivo, por exemplo Key not found, This key belongs to another product, Domain limit reached ou License expired on seguido de uma data. Após mudar o endereço da loja, ou depois de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, o módulo continua funcionando com o último status conhecido.
Uma chave funciona em um domínio: o domínio da loja principal, também em uma configuração multistore. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Flutterwave não é exibida aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A vitrine do PrestaShop não sabe que você está logado no back office, então o método de pagamento também fica oculto para você: você pode configurar o módulo antes de comprar uma chave, mas não pode testá-lo na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Flutterwave não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se a chave secreta do modo atual está preenchida e corresponde ao modo: uma chave de teste (FLWSECK_TEST-…) no modo de teste, uma chave de produção (FLWSECK-…) no modo de produção. A página de configurações mostra um aviso caso contrário. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: o webhook não está funcionando. No painel da Flutterwave, verifique se a URL do webhook é exatamente a exibida em Webhook URL, no modo que você usa (teste ou produção), e se o hash secreto dele é igual a Secret Hash no módulo. Transferências bancárias, USSD e dinheiro móvel pendentes permanecem assim até que a Flutterwave as confirme. O pedido também é criado quando o cliente volta à loja depois de pagar. Ative Debug log e veja o campo Log na página do módulo.
O webhook responde Invalid hash ou Secret hash not configured: o hash secreto no painel da Flutterwave é diferente do que está no módulo, ou o módulo não tem nenhum. Informe o mesmo valor nos dois lugares.
O webhook responde Verification failed, Busy, retry later ou Order could not be created, retry later: não foi possível contatar a Flutterwave para verificar o pagamento, a transação ainda não está visível, o carrinho estava sendo processado por outra requisição, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Flutterwave tenta o webhook novamente. O log mostra o motivo.
A URL do webhook mostra Empty body no navegador: isso é normal. A URL aceita somente webhooks da Flutterwave.
O cliente vê Payment gateway is not properly configured: a chave secreta do modo atual está ausente ou pertence ao outro modo.
O cliente vê We could not match this payment to an order: o link de retorno traz uma referência que não pertence ao carrinho do cliente. Se o cliente foi cobrado, localize o pagamento no painel da Flutterwave.
A Flutterwave mostra um erro na página dela, ou o cliente vê Flutterwave could not start the payment: a sua conta Flutterwave pode não aceitar a moeda do carrinho ou as opções de pagamento selecionadas.
O pedido está em Flutterwave payment on hold após o pagamento: leia as notas no bloco Flutterwave payment (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está configurada. Informe-a e tente novamente.
O reembolso responde Another operation on this payment is running: outro reembolso do mesmo pedido estava sendo enviado naquele momento. Aguarde um pouco, verifique o histórico de reembolsos e tente novamente, se necessário.
Para desenvolvedores, o README do módulo lista os hooks actionWcpFlutterwavePaymentRequest (dados enviados à Flutterwave) e actionWcpFlutterwaveCurrencyDecimals (precisão da moeda).
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Flutterwave Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados de pagamento da Flutterwave e os reembolsos dos pedidos, bem como os status de pedido Awaiting Flutterwave payment e Flutterwave payment on hold, são sempre mantidos, de modo que os pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Flutterwave é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Flutterwave nem endossado por ela.