VibeFox Flow for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo.
PHP: 8.0 ou superior.
Moeda da loja: peso chileno (CLP) ou dólar americano (USD). Para outras moedas, o método de pagamento fica oculto na finalização de compra. Em lojas com CLP, defina WooCommerce > Settings > General > Number of decimals como 0, pois a Flow cobra pesos inteiros.
Conta Flow: você precisa da API Key e da Secret Key da sua conta Flow, na Flow em Mis datos, Datos técnicos. Para testes, crie uma conta de teste separada em sandbox.flow.cl e use suas chaves. As chaves de teste e produção são diferentes. Não é preciso configurar nada na conta Flow.
Site público: as URLs de confirmação, retorno e reembolso da sua loja devem estar acessíveis pela internet, sem modo de manutenção, proteção por senha ou firewall bloqueando a Flow.
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_flow_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Flow.cl > Manage, ou clique em Settings abaixo do nome do plugin na página de plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira a API Key e a Secret Key de teste, ative Enable / Disable, salve e faça um pedido de teste.
6. Para aceitar pagamentos reais, preencha as chaves de produção e desmarque Sandbox mode.
Configuração
Todas as configurações ficam em uma página: WooCommerce > Settings > Payments > Flow.cl. Acima dos campos, a página avisa quando as chaves do modo atual estão vazias (a Flow fica oculta na finalização de compra), quando a moeda da loja não é aceita e quando uma loja com CLP usa casas decimais (a Flow cobra pesos inteiros, então defina Number of decimals como 0 para que preços, totais e reembolsos coincidam exatamente). No modo de teste, mostra Sandbox mode — os pagamentos vão para sandbox.flow.cl, sem cobrança de dinheiro real. Na lista de métodos de pagamento, a Flow é marcada como precisando de configuração até que o modo atual tenha chaves e exibe um selo de modo de teste no ambiente de teste.
Geral
Enable / Disable: Enable Flow.cl payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Flow.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with Webpay, credit or debit card, bank transfer and other methods. You will be redirected to Flow to complete the payment.
Credenciais da API Flow
Copie a API Key e a Secret Key da sua conta Flow (Mis datos, Datos técnicos): chaves de produção em www.flow.cl, chaves de teste em sandbox.flow.cl (uma conta de teste separada).
Sandbox mode: Use the Flow sandbox (sandbox.flow.cl) and the sandbox keys. Não há cobrança de dinheiro real no modo de teste. Padrão: ativado. Desative-o e preencha as chaves de produção para aceitar pagamentos reais. Reembolsos sempre usam o ambiente em que o pedido foi pago.
Sandbox API Key: a API Key da sua conta sandbox.flow.cl.
Sandbox Secret Key: a Secret Key da sua conta sandbox.flow.cl. Ela é usada para assinar cada solicitação.
Live API Key: a API Key da sua conta www.flow.cl.
Live Secret Key: a Secret Key da sua conta www.flow.cl. Mantenha-a em sigilo.
Notificações
O plugin envia três URLs à Flow com cada pagamento e reembolso, portanto não é preciso configurar nada na conta Flow. A seção lista essas URLs:
A confirmação contém apenas um token de pagamento. O plugin então consulta o status do pagamento na Flow com uma solicitação assinada no ambiente em que o pagamento foi criado e aplica apenas a resposta da Flow. Um pagamento que esta loja não criou para o pedido é rejeitado. Sem a confirmação, o pedido é atualizado quando o cliente retorna da Flow.
Avançado
Debug log: Log API calls and notifications em WooCommerce > Status > Logs, origem wcp_flow_gateway, sem chaves ou dados do cliente. Os erros sempre são registrados. Padrão: desativado.
Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Flow data saved on orders is kept). Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Flow) e faz o pedido. No modo de teste, a finalização de compra mostra SANDBOX MODE — os pagamentos vão para o ambiente de teste da Flow. Sem cobranças reais. É necessário um e-mail de faturamento válido. O plugin cria um pagamento Flow para o total do pedido na moeda do pedido, com o assunto Order # seguido do número do pedido e do nome do site, e envia o cliente à página de pagamento da Flow. Lá, o cliente escolhe um método habilitado na sua conta Flow.
Após pagar, o cliente retorna à sua loja. O pedido só é marcado como pago após a confirmação da Flow: pela confirmação ou por uma solicitação de status assinada quando o cliente retorna. Um pedido pago, ou um cupom de dinheiro aguardando pagamento, leva à página de pedido recebido.
Se o pagamento for rejeitado, o cliente volta à página Pay for order (ou à finalização de compra) com Your Flow payment was rejected. Please try again or choose another payment method. Se o cliente sair da página da Flow sem pagar, a mensagem é The Flow payment was not completed. You can try again or choose another payment method. Se não for possível verificar o resultado, a mensagem é We could not confirm your Flow payment yet. If you completed it, you will receive a confirmation e-mail shortly; otherwise please try again. Cada nova tentativa cria um novo pagamento Flow vinculado ao pedido.
Se a Flow não conseguir iniciar o pagamento, o cliente verá uma mensagem curta, por exemplo Could not connect to Flow. Please try again in a moment. Os detalhes ficam no log.
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 para os clientes são traduzidos para espanhol (Chile e Espanha).
O plugin aceita apenas pagamentos únicos. Não há cartões salvos, assinaturas, cobranças recorrentes ou links de pagamento, e ele não pré-seleciona um método de pagamento Flow. A Flow não pode cancelar um link de pagamento já criado: se um cliente pagar um link antigo depois de pagar um mais recente, o pedido receberá uma nota pedindo que você reembolse a duplicata na Flow.
Pedidos e reembolsos
Status dos pedidos
Pending payment: o cliente foi enviado à Flow e ainda não pagou. A nota do pedido mostra o valor e o número de pedido Flow da tentativa.
On hold, awaiting coupon payment: o cliente gerou um cupom de pagamento Servipag ou Multicaja. O pedido muda quando a Flow confirma o pagamento.
Processing: a Flow informou que o pagamento foi efetuado e o valor e a moeda coincidem (pedidos apenas com produtos virtuais baixáveis passam para Concluído, o padrão do WooCommerce). A nota do pedido mostra o valor e o número de pedido Flow. O ID da transação do pedido é o número de pedido Flow.
On hold, amount/currency mismatch: a Flow informou valor ou moeda diferentes dos do pedido. O pedido não foi marcado como pago; verifique-o manualmente.
On hold, payment for a cancelled order: chegou um pagamento para um pedido que havia sido cancelado sem ser pago. Confira o pedido e envie-o ou reembolse o pagamento na Flow.
Failed: a Flow rejeitou a última tentativa de pagamento de um pedido não pago. O cliente pode tentar novamente.
Cancelled: a última tentativa de pagamento foi anulada na Flow.
Se chegar outro pagamento para um pedido já pago, o pedido não muda. Uma nota pede que você reembolse a duplicata na sua conta Flow. Um pedido pago e depois cancelado ou reembolsado nunca é reaberto.
Reembolsos
Abra o pedido, clique em Refund, insira o valor e clique em Refund via Flow. Há suporte a reembolsos totais e parciais. O reembolso é enviado ao ambiente em que o pedido foi pago (teste ou produção), portanto as chaves desse ambiente devem estar configuradas e o pedido precisa de um e-mail de faturamento. A Flow envia um e-mail ao cliente para concluir o reembolso. Se a Flow recusar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Uma solicitação bem-sucedida é adicionada às notas do pedido com o número e o status do reembolso Flow.
Alterações posteriores no status do reembolso informadas pela Flow são adicionadas às notas do pedido. Se a Flow rejeitar ou cancelar um reembolso depois, a nota informa que o dinheiro não foi devolvido ao cliente; o registro de reembolso do WooCommerce é mantido, então trate isso manualmente. Reembolsos criados no painel da Flow não são importados para o WooCommerce.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > Flow.cl. 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 inserir 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 Flow 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 ainda veem 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: pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.
Quando a 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 Flow não aparece na finalização de compra: verifique se a licença está ativa, Enable / Disable está ativado, as chaves do modo atual estão preenchidas (chaves de teste no modo de teste, de produção no modo de produção) e a moeda da loja é CLP ou USD. Na página Pay for order, a moeda do pedido é verificada.
O pagamento foi feito, mas o pedido continua como Pending payment: a confirmação da Flow não chega à sua loja e o cliente não retornou. Verifique se a URL de confirmação exibida nas configurações é acessível pela internet e não está bloqueada por manutenção, senha ou firewall. Ative Debug log e consulte WooCommerce > Status > Logs, origem wcp_flow_gateway.
A confirmação responde Payment does not belong to the order ou Unknown order: o pagamento não foi criado por esta loja para este pedido ou foi criado em outro ambiente. O pedido não muda.
A confirmação responde Gateway not configured: as chaves do ambiente do pagamento estão vazias. Insira-as novamente.
A confirmação responde Flow API unavailable: a solicitação de status à Flow falhou. A Flow tenta a confirmação novamente.
O cliente vê Flow payments are not available at the moment: as chaves estão ausentes ou foram recusadas pela Flow. Confira a API Key e a Secret Key do modo atual.
O cliente vê A valid billing email is required for Flow payments: a Flow precisa do e-mail do cliente.
O cliente pagou, mas o pedido está On hold: leia a nota do pedido. O cliente gerou um cupom de dinheiro ainda não pago, ou o valor ou a moeda informados pela Flow não coincidem com o pedido. Totais CLP com casas decimais são arredondados para pesos inteiros, então defina Number of decimals como 0.
O reembolso falha com uma mensagem sobre chaves de teste ou produção: o pedido foi pago nesse ambiente e suas chaves estão vazias. Insira-as e tente novamente.
O bloco de licença mostra um erro: siga a mensagem do bloco. Por exemplo, se a chave já estiver em uso 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 para o novo domínio. Se o servidor de licenças estiver inacessível, o plugin continua funcionando com o último status conhecido.
Para desenvolvedores, o readme lista o filtro wc_flw_supported_currencies (moedas para as quais o gateway é oferecido).
Desinstalação
Ao desativar o plugin, todos os dados são mantidos. Para removê-lo, desative-o e exclua-o na página Plugins. A chave e o status da licença deste plugin sempre são removidos. As configurações do gateway e os logs só são removidos se Delete data on uninstall estava ativado. Caso contrário, ficam para uma reinstalação futura. Os dados Flow salvos nos pedidos sempre são mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Flow é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado à Flow nem endossado por ela.