VibeFox Flutterwave for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não permite a ativação sem o WooCommerce.

PHP: 8.0 ou superior. O plugin não permite a ativação em versões anteriores do PHP.

Conta Flutterwave: você precisa das chaves secretas da sua conta Flutterwave, disponíveis 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. Configure também um webhook com um hash secreto de sua escolha (consulte Configuração).

Moedas: o pedido é sempre cobrado na moeda do pedido. O plugin não restringe países nem moedas; a Flutterwave mostra um erro se sua conta não aceitar a moeda.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_flutterwave_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Flutterwave > Manage, ou clique em Settings abaixo do nome do plugin na página de plugins.

4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Digite suas chaves secretas, configure o webhook no painel da Flutterwave e informe o mesmo hash secreto no plugin (consulte Configuração).

6. Ative Enable/Disable, teste um pagamento no modo de teste e depois marque Live mode.

Configuração

Todas as configurações ficam em uma página: WooCommerce > Settings > Payments > Flutterwave. 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; o método de pagamento fica oculto na finalização de compra até que isso seja corrigido. Ela também avisa quando não há hash secreto do webhook: os webhooks são rejeitados e os pagamentos só são confirmados quando o cliente volta à sua loja. Na lista de métodos de pagamento, a Flutterwave aparece como necessitando de configuração até que o modo atual tenha uma chave secreta, e mostra um selo de modo de teste nesse modo.

Geral

Enable/Disable: Enable Flutterwave Payment ativa ou desativa o método de pagamento. Padrão: off.

Title: o título do método de pagamento que os clientes veem na finalização de compra. Padrão: Flutterwave.

Description: o texto que os clientes veem 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 do painel da Flutterwave em Settings, API keys. Os modos de teste e de produção têm chaves diferentes.

Live mode: Accept real payments (uncheck for test mode). O modo de teste usa a chave secreta de teste e não cobra dinheiro real. O modo de produção usa a chave secreta de produção. Padrão: off (modo de teste).

Test Secret Key: sua chave secreta de teste da Flutterwave (FLWSECK_TEST-...).

Live Secret Key: sua chave secreta de produção da Flutterwave (FLWSECK-...).

Webhook

O webhook confirma pagamentos mesmo quando o cliente não volta à sua loja. No painel da Flutterwave, em Settings, Webhooks, digite a Webhook URL mostrada nesta seção e um hash secreto de sua escolha, tanto no modo de teste quanto no de produção. A URL tem o formato https://your-site/wc-api/flw_p_webhook/. O plugin reage a este evento:

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. Webhooks sem um hash secreto válido são rejeitados. Sem o webhook, um pagamento só é confirmado quando o cliente volta à sua loja.

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 é limpa ao salvar.

Autocomplete Orders: Automatically mark orders as completed after successful payment. Se ativado, os pedidos passam a Concluído em vez de Processando após o pagamento, com uma única mudança de status. Padrão: off.

Avançado

Debug log: Log Flutterwave API events for debugging em WooCommerce > Status > Logs, origem wcp_flutterwave_payment. Os erros são sempre registrados. Chaves e dados de clientes nunca são registrados. Padrão: off.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. Desativar o plugin nunca exclui nada. Os dados de pagamento salvos nos pedidos são sempre mantidos. Padrão: off.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Flutterwave) e faz o pedido. No modo de teste, a finalização de compra mostra TEST MODE - no real payments will be processed. É necessário um e-mail de cobrança válido. O plugin cria um pagamento Flutterwave para o total do pedido na moeda do pedido, com e-mail, telefone e nome do cliente, nome e logotipo do seu site, e envia o cliente à página de finalização de compra da Flutterwave. Lá, o cliente paga com um dos métodos ativados na sua conta (ou listados em Payment Options).

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago após a confirmação da Flutterwave: pelo webhook ou por uma verificação no servidor quando o cliente volta. Se o pagamento ainda não foi confirmado, por exemplo uma transferência bancária ou um pagamento USSD ou de dinheiro móvel pendente, a página de pedido recebido mostra Your payment is being confirmed by Flutterwave. You will receive an e-mail as soon as it is confirmed. Se o dinheiro chegou, mas o plugin colocou o pedido em Aguardando para revisão, por exemplo porque o valor pago não corresponde ao pedido, a página mostra Your payment was received and your order is being reviewed. We will contact you if anything is needed.

Se o pagamento for recusado, o cliente volta à finalização de compra (ou à página Pay for order) com Your payment was declined. You can try again or choose another payment method. Se cancelar na página da Flutterwave, um pedido feito na finalização de compra é cancelado, um pedido criado manualmente continua não pago e a mensagem é Payment was cancelled. You can try again or choose another payment method. Se o pagamento não foi concluído, a mensagem é The payment was not completed. You can try again or choose another payment method.

Um cliente pode tentar pagar novamente um pedido não pago. Cada tentativa tem sua própria referência, e um link antigo pago depois continua sendo aceito. Se a Flutterwave não conseguir iniciar o pagamento, o cliente verá uma mensagem curta, por exemplo Flutterwave is temporarily unavailable. Please try again in a moment or choose another payment method.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com WooCommerce High-Performance Order Storage (HPOS). Os textos destinados aos clientes são traduzidos para francês.

O plugin 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, então um link antigo de um pedido ainda pode ser pago.

Pedidos e reembolsos

Status dos pedidos

Pending payment: o cliente foi enviado à Flutterwave e ainda não pagou, ou o pagamento continua pendente na Flutterwave.

Processing or Completed: o pagamento foi confirmado. Concluído é usado quando Autocomplete Orders está ativado (pedidos apenas com produtos virtuais baixáveis também passam a Concluído, o padrão do WooCommerce). A nota do pedido mostra valor, método de pagamento, referência Flutterwave, transação e modo. O ID de transação do pedido é a referência Flutterwave.

On hold after payment: o valor ou a moeda verificados não correspondiam ao pedido, ou o pagamento chegou após o cancelamento do pedido. A nota explica o motivo. Atenda o pedido ou reembolse o pagamento. Um webhook repetido nunca reabre um pedido reembolsado ou cancelado.

Failed: a Flutterwave informou que a última tentativa de pagamento de um pedido pendente falhou ou foi cancelada. A nota mostra o motivo.

Cancelled: o cliente cancelou na página da Flutterwave após fazer o pedido na finalização de compra, ou o pedido foi cancelado por você ou pelo fim do prazo de reserva de estoque do WooCommerce.

Se um segundo pagamento for recebido para um pedido já pago, o pedido não será alterado. Uma nota pede que você reembolse o pagamento duplicado no painel da Flutterwave.

Reembolsos

Abra o pedido, clique em Refund, digite o valor e clique em Refund via Flutterwave. Há suporte a reembolsos totais e parciais. O reembolso é enviado com a chave secreta do modo em que o pagamento foi feito (teste ou produção), portanto essa chave deve estar configurada. Se a Flutterwave rejeitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID e o status do reembolso (concluído ou iniciado com o status informado pela Flutterwave).

Os reembolsos feitos no painel da Flutterwave não são sincronizados com o WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem Refund via Flutterwave.

Chave de licença

O plugin funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Flutterwave. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa e seu domínio. Use Check now para verificar o status novamente, Change key para digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera sua vaga de 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 verá This payment method is not available. Please choose another one. Os gerentes de loja conectados continuam vendo o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página de plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática em segundo plano.

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á ativado 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. Caso contrário, a página de configurações mostra um aviso.

O pagamento foi feito, mas o pedido continua Pending payment: o webhook não está funcionando. No painel da Flutterwave, verifique se a URL do webhook é exatamente a mostrada nas configurações, no modo usado (teste ou produção), e se o hash secreto é igual a Secret Hash no plugin. Transferências bancárias, USSD e dinheiro móvel pendentes continuam pendentes até a confirmação da Flutterwave. Ative Debug log e consulte WooCommerce > Status > Logs, origem wcp_flutterwave_payment.

O webhook responde Invalid hash ou Secret hash not configured: o hash secreto no painel da Flutterwave difere do informado no plugin, ou o plugin não tem um. Digite o mesmo valor nos dois locais.

O webhook responde Verification failed ou Busy, retry later: não foi possível acessar a Flutterwave para verificar o pagamento, a transação ainda não está visível ou outra solicitação estava atualizando o pedido. A Flutterwave tenta enviar o webhook novamente.

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 contém uma referência que esta loja não criou. Se o cliente foi cobrado, localize o pagamento no painel da Flutterwave.

A Flutterwave mostra um erro na própria página: sua conta Flutterwave pode não aceitar a moeda do pedido ou as opções de pagamento selecionadas.

O pedido fica On hold após o pagamento: leia a nota do pedido. O valor ou a moeda verificados não correspondiam ao pedido, ou o pagamento chegou após o cancelamento do pedido. Atenda 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. Digite-a e tente novamente.

O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver sendo usada em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Para desenvolvedores, a documentação do plugin lista os filtros flw_p_payment_request (dados enviados à Flutterwave), flw_p_currency_decimals (precisão da moeda) e flw_p_icon (ícone na finalização de compra).

Desinstalação

Ao desativar o plugin, todos os dados são mantidos. Para removê-lo, desative e exclua o plugin na página Plugins. A chave e o status de licença deste plugin são sempre removidos. As configurações do gateway e os logs são removidos apenas se Delete data on uninstall estava ativado. Caso contrário, ficam para uma reinstalação posterior. Os dados Flutterwave salvos nos pedidos são sempre mantidos. Os pedidos existentes mantêm as notas de pagamento e os IDs de transação.

Flutterwave é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado à Flutterwave nem endossado por ela.