VibeFox Flow for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não instala em versões anteriores do PHP.
Moeda: peso chileno (CLP) ou dólar americano (USD). Para carrinhos em outras moedas, o método de pagamento fica oculto na finalização de compra. Para o CLP, defina a precisão da moeda CLP como 0 em International > Localization > Currencies, porque 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 as chaves dela. Chaves de teste e de 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 precisam estar acessíveis pela internet, sem proteção por senha nem firewall que bloqueie a Flow. O modo de manutenção da loja não as bloqueia.
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, mais tarde, encontre VibeFox Flow Gateway na lista de módulos e clique em Configure.
3. Insira 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. Insira a API Key e a Secret Key de teste, ative Enable / Disable, clique em Save e faça um pedido de teste.
5. Para aceitar pagamentos reais, preencha as chaves de produção e desative Sandbox mode.
Na instalação, o módulo cria dois status de pedido, Awaiting Flow payment e Flow 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 Flow Gateway > Configure. Cada seção com campos tem seu próprio botão Save, que salva a página inteira. 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 padrão da loja não é CLP ou USD e quando a moeda CLP tem casas decimais (defina a precisão dela como 0 para que preços, totais e reembolsos coincidam exatamente). No modo de teste, ela mostra Sandbox mode — payments go to sandbox.flow.cl, no real money is charged.
Flow.cl
Enable / Disable: Enable Flow.cl payments liga ou desliga o método de pagamento. Padrão: off.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Flow. Obrigatório.
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: usa o sandbox da Flow (sandbox.flow.cl) e as chaves de teste. No modo de teste, nenhum valor real é cobrado. Padrão: on. Desative 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.
Chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.
Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Notificações
O módulo envia três URLs à Flow com cada pagamento e reembolso, então não é preciso configurar nada na conta Flow. O campo Flow URLs desta seção as lista. Com URLs amigáveis, elas têm este formato:
A confirmação contém apenas um token de pagamento. O módulo procura o token entre os pagamentos que ele criou, pede à Flow o status do pagamento 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 é rejeitado sem consultar a Flow. Sem a confirmação, o pedido é criado quando o cliente retorna da Flow.
Avançado
Debug log: grava chamadas de API e notificações em logs/flw_p_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados do cliente nunca são registrados. Erros são sempre registrados, mesmo com a opção desligada. Padrão: off.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ligado, desinstalar o módulo remove as configurações e o log. Dados da Flow salvos nos pedidos são mantidos. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Flow) e vê a descrição. No modo de teste, aparece SANDBOX MODE — os pagamentos vão para o sandbox da Flow. Não há cobranças reais. Após confirmar, o módulo cria um pagamento na Flow pelo total do carrinho na moeda do carrinho, com o assunto Cart # seguido do número do carrinho e do nome da loja, e envia o cliente à página de pagamento da Flow. O e-mail do cliente é repassado à Flow. Lá, o cliente escolhe um método de pagamento habilitado na sua conta Flow. Neste ponto ainda não existe pedido.
Depois de pagar, o cliente retorna à sua loja. O pedido só é marcado como pago quando a Flow confirma: pela confirmação ou por uma solicitação de status assinada quando o cliente retorna. Então o pedido é criado e o cliente vê a página padrão de confirmação de pedido com Your payment with Flow has been received. Se o cliente gerou um cupom Servipag ou Multicaja, o pedido é criado em Awaiting Flow payment e a página mostra Your Flow payment coupon was generated. The order will be processed as soon as Flow confirms the payment. Se o pagamento de um pedido com cupom falhar ou for cancelado depois, a página mostra Your Flow payment was not completed. Please contact us about this order. Se o valor não correspondia, a página mostra Your Flow payment was received and is being reviewed by the shop.
Se a Flow não puder ser acessada quando o cliente retornar, ou se outra solicitação estiver criando o pedido naquele momento, uma página Payment confirmation pede ao cliente que não pague novamente e oferece Check again e Back to checkout.
Se o pagamento foi recusado, o cliente volta à finalização de compra com Your Flow payment was rejected. Please try again or choose another payment method. Se o cliente saiu 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 o resultado não puder ser verificado, 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. O carrinho é mantido, e cada nova tentativa cria um novo pagamento Flow vinculado ao carrinho.
Se a Flow não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Could not connect to Flow. Please try again in a moment. Os detalhes estão no log.
Se um cupom do carrinho deixar de ser válido entre o pagamento e a sua confirmação, o PrestaShop o remove do pedido. O pedido então vai para Flow payment on hold com uma nota, porque o cliente pagou o preço com desconto.
O módulo 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 que o carrinho já foi pago, o pedido recebe uma nota pedindo que você reembolse o duplicado na Flow.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à Flow e não pagou, ou a Flow ainda não confirmou o pagamento. Só existe o carrinho.
Payment accepted: a Flow informou o pagamento como pago e o valor e a moeda conferem. O pagamento é registrado com o número do pedido da Flow como ID da transação, e uma nota mostra o valor, o número do pedido da Flow e o método de pagamento.
Awaiting Flow payment: o cliente gerou um cupom de pagamento Servipag ou Multicaja. O pedido passa para Payment accepted quando a Flow confirma o pagamento.
Flow payment on hold: a Flow informou um valor ou moeda diferente do total do pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou), um cupom foi removido, ou chegou um pagamento para um pedido que havia sido cancelado. O pagamento cobrado pela Flow é registrado e a nota explica. Verifique o pedido e envie-o ou reembolse o pagamento.
Payment error: a Flow recusou o pagamento por cupom de um pedido em espera.
Canceled: o pagamento por cupom de um pedido em espera foi anulado na Flow.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se outro pagamento chegar para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o duplicado na sua conta Flow. Um pedido reembolsado nunca é reaberto.
Bloco de pagamento da Flow
A página do pedido mostra um bloco Flow payment com o número do pedido da Flow e o método de pagamento, a referência commerceOrder, o status do pagamento, o valor pago e reembolsado, um selo Sandbox para pagamentos de teste, o histórico de reembolsos e as Flow notes do pedido.
Reembolsos
No bloco Flow payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Flow. Confirme a pergunta Refund this amount via Flow? Flow e-mails the customer to complete the refund. Reembolsos totais e parciais são suportados. Você precisa ter permissão para editar pedidos. Os reembolsos são limitados ao valor que a Flow efetivamente cobrou, então, após uma divergência de valor, você pode reembolsar até o que o cliente pagou, e não o total do pedido. Reembolsos em CLP devem ser valores inteiros. O reembolso é enviado ao ambiente em que o pagamento foi feito (teste ou produção), então as chaves desse ambiente precisam estar preenchidas, e o cliente precisa de um e-mail válido. Se a Flow recusar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Uma solicitação bem-sucedida é adicionada ao histórico de reembolsos e às notas, com o número e o status do reembolso da Flow. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status. Reembolsos ficam disponíveis assim que a Flow confirma o pagamento.
Mudanças posteriores de status do reembolso informadas pela Flow são adicionadas às notas. Se a Flow recusar ou cancelar um reembolso depois, a nota informa que o dinheiro não foi devolvido ao cliente, e o valor pode ser reembolsado novamente. O módulo não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Flow. Reembolsos criados no painel da Flow não são importados para o PrestaShop.
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 Flow Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Flow Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: presta-payment-flow 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 Flow 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. 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 inserida, 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 Flow não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ligado, se as chaves do modo atual estão preenchidas (chaves de teste no modo de teste, chaves de produção no modo de produção) e se a moeda do carrinho é CLP ou USD. Em Payment > Preferences, verifique se o módulo está liberado para a moeda do carrinho, o país do cliente e o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado: a confirmação da Flow não chega à sua loja e o cliente não retornou. Verifique se a URL de confirmação mostrada em Flow URLs abre a partir da internet e não é bloqueada por proteção por senha ou firewall. Ative o Debug log e veja o campo Log na página do módulo.
A confirmação responde Payment does not belong to the order: o token não é um pagamento criado por esta loja, ou a Flow informou outra referência para ele. Nada é alterado.
A confirmação responde Gateway not configured: as chaves do ambiente do pagamento estão vazias. Digite-as novamente. A Flow repete a confirmação.
A confirmação responde Flow API unavailable or Busy, retry: a solicitação de status à Flow falhou, ou o pedido estava sendo criado por outra solicitação no mesmo momento. A Flow repete a confirmação.
O cliente vê Flow payments are not available at the moment: as chaves estão ausentes ou a Flow as recusou. Verifique 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 vê The order total is too small to be paid with Flow: o total do carrinho arredonda para zero na moeda do carrinho.
O cliente pagou, mas o pedido está em Awaiting Flow payment ou Flow payment on hold: leia as notas no bloco Flow payment. O cliente gerou um cupom de pagamento em dinheiro que ainda não foi pago, ou o valor ou a moeda informados pela Flow não correspondem ao pedido. Totais em CLP com decimais são arredondados para pesos inteiros, então defina a precisão do CLP como 0.
O reembolso falha com uma mensagem sobre as chaves de teste ou de produção: o pedido foi pago nesse ambiente e as chaves dele estão vazias. Preencha-as e tente novamente.
O reembolso falha com Flow accepts CLP refunds in whole units only: digite um valor inteiro.
Para desenvolvedores, o README lista os hooks actionWcpFlowSupportedCurrencies (moedas para as quais o método de pagamento é oferecido) e actionWcpFlowPaymentSubject (o assunto do pagamento enviado à Flow).
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Flow Gateway 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 ligado, as configurações do módulo e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação futura. Os registros de pagamentos e reembolsos da Flow e os status de pedido Awaiting Flow payment e Flow payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Flow é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Flow.