VibeFox Windcave 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 mais antigas do PHP.
Conta na Windcave: você precisa de uma conta de comerciante na Windcave com credenciais da REST API: um nome de usuário da API e uma chave de API. A Windcave emite essas credenciais separadamente para o ambiente de testes UAT (uat.windcave.com) e para produção (sec.windcave.com). Solicite-as ao suporte da Windcave ou ao seu gerente de conta. As chaves PxPay não funcionam com este módulo. Os métodos de pagamento que você quer oferecer (cartões, carteiras digitais e outros) precisam estar habilitados na sua conta Windcave.
Notificação: a sua loja precisa estar acessível pela internet, para que a Windcave possa enviar a notificação de pagamento. Nada precisa ser configurado na Windcave para isso.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 VibeFox Windcave Payment Gateway na lista de módulos e clique em Configure.
3. Informe a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Informe o seu nome de usuário e a chave da REST API: as credenciais UAT para o modo de teste e as credenciais de produção para pagamentos reais (veja Configuração).
5. Escolha o tipo de transação e os métodos de pagamento, ative Enable/Disable e clique em Save. Faça um pagamento de teste com Test mode ativado e depois desative Test mode para receber pagamentos reais.
Ao instalar, o módulo cria o status de pedido Windcave payment on hold. O PrestaShop oferece o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-los em Payment > Preferences.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Enquanto o modo de teste estiver ativado, a página mostra Test mode ativado: os pagamentos vão para o ambiente UAT da Windcave e nenhum dinheiro real é cobrado. Se o módulo estiver ativado, mas o modo atual não tiver nome de usuário ou chave de API, a página avisa que o método de pagamento está oculto no checkout, por exemplo A Windcave está ativada, mas o nome de usuário ou a chave de API UAT estão vazios — o método de pagamento está oculto no checkout. O Title não pode ficar vazio: nesse caso a página mostra Informe um título para o método de pagamento. e nada é salvo.
Windcave
Enable/Disable: Enable Windcave payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê no checkout. Também é o nome do método de pagamento salvo no pedido. Padrão: Credit/Debit Card (Windcave). Obrigatório.
Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: You will be redirected to the secure Windcave payment page to complete your payment.
Windcave REST API
Informe as credenciais da REST API emitidas pela Windcave (nome de usuário e chave de API, não as chaves PxPay). As credenciais de produção e as UAT podem ser salvas lado a lado. O modo de teste usa somente as credenciais UAT, e o modo real usa somente as de produção. A seção traz um link para a documentação da REST API da Windcave.
Test mode: usa o ambiente de testes UAT da Windcave (uat.windcave.com). Nenhum dinheiro real é cobrado. Os novos pagamentos usam as credenciais UAT. Reembolsos e capturas sempre vão para o ambiente em que o pedido foi pago. Padrão: desativado.
Production API username: o nome de usuário da REST API para sec.windcave.com.
Production API key: a chave da REST API para sec.windcave.com.
UAT API username: o nome de usuário da REST API para uat.windcave.com (modo de teste).
UAT API key: a chave da REST API para uat.windcave.com (modo de teste).
As chaves de API salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo apenas se quiser alterá-lo.
Clear saved keys: marque Production API key ou UAT API key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Notification URL: mostra o endereço para o qual a Windcave envia a sua notificação de pagamento (Fail-Proof Result Notification). Com URLs amigáveis, ele fica assim: https://sua-loja/module/wcp_windcave_payment_gateway/notification. Não há nada a configurar na Windcave: o módulo envia seus endereços de retorno e este endereço de notificação em cada sessão de pagamento. O endereço precisa estar acessível pela internet; caso contrário, os pedidos só são confirmados quando o cliente volta da Windcave. Nem o retorno do cliente nem a notificação são assinados pela Windcave, por isso o módulo nunca confia neles sozinho: ele sempre lê o resultado da sessão pela REST API da Windcave, com as credenciais do ambiente em que a sessão foi criada.
Payment
Transaction type: como o pagamento é cobrado. Padrão: Purchase.
Payment methods: os métodos exibidos na página de pagamento da Windcave: Cards, Account2Account (transferência bancária da Nova Zelândia), Apple Pay, Google Pay, PayPal, Alipay, WeChat Pay, UnionPay, Interac, humm. Use Ctrl ou Cmd e clique para selecionar vários. Os métodos precisam estar habilitados na sua conta Windcave. Deixe o campo vazio para exibir todos os métodos habilitados na conta. Padrão: Cards.
Advanced
Debug log: registra as requisições à API e os eventos de pagamento em logs/windcave_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Enquanto esta opção estiver desativada, apenas erros e avisos são registrados. Chaves de API, dados do cartão e dados pessoais dos clientes nunca são registrados. Padrão: desativado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Clean uninstall: exclui as configurações e os logs do módulo quando ele é desinstalado. Os dados de pagamento salvos com os pedidos (os IDs de transação da Windcave necessários para reembolsos) são sempre mantidos. Padrão: desativado.
A versão do módulo aparece no fim da página.
Checkout
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Credit/Debit Card (Windcave)) com a sua descrição. No modo de teste, o cliente também vê Test mode: os pagamentos vão para o ambiente UAT da Windcave, nenhum dinheiro real é cobrado. Depois de confirmar, o módulo cria uma sessão de pagamento da Windcave para o total do carrinho na moeda do carrinho e envia o cliente para a Windcave Hosted Payment Page. O número do carrinho é enviado como referência do comerciante, junto com o idioma da loja e o nome, e-mail, telefone e endereço de cobrança do cliente (e o endereço de entrega, quando o carrinho precisa de envio). Nesse momento ainda não existe pedido.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Windcave confirma: o módulo pede à REST API da Windcave o resultado da sessão, tanto quando o cliente volta quanto quando a notificação da Windcave chega. Um bloqueio por carrinho garante que o pagamento seja aplicado apenas uma vez. Em seguida o pedido é criado, e o cliente vê a página padrão de confirmação do pedido com Your Windcave payment has been received. Para um pedido em espera (uma autorização ou um pagamento que não corresponde ao carrinho), a página mostra Your payment was received by Windcave. The shop will check it before processing your order — please do not pay again.
Se o cliente voltar de um pagamento aprovado, mas o resultado ainda não for conhecido, uma página de Payment confirmation mostra We are waiting for Windcave to confirm your payment. You will receive an e-mail as soon as it is confirmed — please do not pay again. e um botão Check again. A notificação cria o pedido assim que a Windcave confirma o pagamento.
Se o cliente voltar sem um pagamento concluído, a página do checkout mostra uma destas mensagens. O carrinho é mantido.
O cliente pode tentar novamente com o mesmo carrinho. Uma nova tentativa verifica primeiro a sessão anterior: se ela já estiver paga, o pedido é criado e nenhum segundo pagamento é iniciado; se o cliente nunca usou a página de pagamento e o carrinho não mudou, ele é enviado de volta para a mesma página. Se o pagamento anterior estiver sendo confirmado naquele momento, o cliente vê Your previous payment for this order is being confirmed right now. Please wait a minute and check your e-mail before trying again.
Se a Windcave não conseguir iniciar o pagamento, o cliente permanece no checkout com uma mensagem curta: que a Windcave não conseguiu iniciar o pagamento com os dados deste pedido, ou que o serviço de pagamento está temporariamente indisponível. O motivo é registrado no log. Se o modo atual não tiver credenciais, o cliente vê This payment method is not available at the moment. Please choose another payment method or contact us.
A notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
O módulo não tem assinaturas nem pagamentos recorrentes, cartões salvos, formulário de cartão incorporado ao seu site (o cliente sempre paga na página da Windcave), suporte à API PxPay 2.0, e não adiciona sobretaxas. Se a Windcave adicionar uma sobretaxa, o pedido é comparado com a transação principal.
Pedidos e reembolsos
Order statuses
No order yet: o cliente foi enviado à Windcave e não pagou, a Windcave ainda não confirmou o pagamento, ou o pagamento foi recusado, cancelado ou expirou. Só o carrinho existe.
Payment accepted: um pagamento Purchase foi confirmado e corresponde ao carrinho. O pagamento é registrado com o ID da transação da Windcave, e uma observação mostra o valor, o ID da transação, o código de autorização, o tipo de cartão com o número mascarado e o ambiente (UAT ou produção).
Windcave payment on hold (authorised): um pagamento Auth foi aprovado, mas ainda não capturado. Nenhum pagamento é registrado no pedido até ser capturado. A observação explica como capturá-lo ou liberá-lo.
Windcave payment on hold (does not match): a Windcave informou um valor, uma moeda, uma referência do comerciante ou um tipo de transação diferente do carrinho (por exemplo, o carrinho foi alterado em outra aba depois que o pagamento começou). A observação lista as diferenças. Para um Purchase na moeda do carrinho, o pagamento é registrado com o valor que a Windcave efetivamente cobrou. Confira o pagamento no Windcave Payline antes de enviar o pedido e reembolse-o, se necessário.
Refunded: o pagamento foi reembolsado integralmente ou a autorização foi liberada pelo módulo.
Se chegar um pagamento aprovado para um pedido cancelado, ou um segundo pagamento aprovado para um pedido já existente, o pedido não é alterado. Uma observação com o ID da transação pede que você o reembolse no Windcave Payline (ou restaure manualmente o pedido cancelado).
Windcave payment block
A página do pedido mostra um bloco Windcave payment com o ID da transação, o ID da sessão, o tipo e o status da transação com o ambiente, o valor pago, o código de autorização e o cartão, a transação de captura ou cancelamento, o total do pagamento e o valor reembolsado, um selo Test mode (UAT) para os pagamentos de teste, o histórico de reembolsos, todas as sessões da Windcave do carrinho e as Windcave notes do pedido.
Capture (Auth mode)
Para um pedido em Windcave payment on hold com uma autorização que ainda não foi capturada nem liberada, o bloco mostra Capture Windcave payment com o valor. Clique e confirme Capture the authorised amount through Windcave now? O valor autorizado é capturado (o total do pedido, a menos que o pagamento não corresponda ao pedido), o pedido passa para Payment accepted e o pagamento é registrado com o ID da transação de captura. Se a Windcave não aceitar a captura, o bloco mostra Windcave capture failed: com o motivo, o motivo é adicionado às observações e o pedido continua em espera.
Refunds
No bloco Windcave payment, informe o valor (é preenchido o valor ainda não reembolsado), opcionalmente um motivo, e clique em Refund via Windcave. Confirme a pergunta Refund this amount through Windcave? This cannot be undone. São aceitos reembolsos totais e parciais. Você precisa ter permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são contabilizados no valor e na moeda aprovados pela Windcave, portanto, após uma divergência, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. Um reembolso após uma captura vai para a transação de captura. O reembolso é enviado para o ambiente (UAT ou produção) e para a conta em que o pagamento foi feito, por isso as credenciais desse ambiente precisam estar salvas. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às observações, com o ID da transação da Windcave. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status.
Para um pagamento Auth que não foi capturado, o botão é Release authorisation (void) e só é possível liberar o valor total. Um valor parcial gera um erro que pede para reembolsar o valor total ou capturar o pagamento antes.
Se a Windcave recusar o reembolso, o bloco mostra Windcave declined the refund: com o motivo, e nenhum reembolso é registrado. Se a Windcave ainda estiver processando o reembolso, o bloco mostra Windcave has not confirmed the refund yet. See the order notes. e o reembolso não é registrado. Confira a transação no Windcave Payline: se foi aprovada, registre o reembolso manualmente; caso contrário, tente novamente. Uma nova tentativa do mesmo reembolso não é enviada duas vezes à Windcave.
O módulo não emite notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela Windcave. Reembolsos feitos no Windcave Payline não são informados à loja.
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 Windcave Payment Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Windcave Payment Gateway > Configure, acima das configurações. Informe a chave em License key e clique em Activate. Depois disso, 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 deles estão a linha Product: presta-payment-windcave 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. Depois que o endereço da loja mudar, ou depois que você 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 único domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, a Windcave não é exibida para os clientes no checkout. 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 testá-lo no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados pela notificação ou quando o cliente volta, e capturas e reembolsos continuam funcionando.
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 e, depois, uma vez por semana. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Windcave não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo atual tem as duas credenciais: UAT API username e UAT API key no modo de teste, Production API username e Production API key no modo real. A página de configurações mostra um aviso quando elas estão faltando. 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 módulo ainda não conseguiu obter o resultado da Windcave. Veja o campo Log na página do módulo: os erros são sempre registrados, por exemplo quando a sessão não pôde ser verificada. Confira se as credenciais do ambiente do pagamento estão salvas e corretas. A verificação é repetida quando a Windcave reenvia a notificação (o módulo responde payment could not be verified yet, retry later com um código de erro, para que a Windcave tente de novo), quando o cliente clica em Check again e quando o cliente inicia um novo pagamento para o mesmo carrinho. O seu servidor precisa aceitar as requisições da Windcave para a Notification URL exibida nas configurações.
A notificação responde order not found: a sessão não foi criada por esta loja, por exemplo uma sessão de outra loja que usa a mesma conta Windcave. Ela é ignorada.
Authentication failed no log: o nome de usuário ou a chave da REST API estão errados, ou pertencem ao outro ambiente. As credenciais UAT funcionam apenas no modo de teste, e as de produção apenas no modo real. As chaves PxPay não funcionam.
O cliente vê que a Windcave não conseguiu iniciar o pagamento com os dados deste pedido: a Windcave rejeitou a solicitação de sessão, por exemplo por causa da moeda ou de um método de pagamento que não está habilitado na sua conta. O motivo exato está no log.
O pedido está em Windcave payment on hold depois do pagamento: leia as observações no bloco Windcave payment. Ou o pagamento é uma autorização Auth aguardando captura, ou o valor pago, a moeda ou a referência do comerciante divergiram do carrinho. Capture, despache ou reembolse o pagamento.
Pagamentos de teste e pagamentos reais: UAT e produção são mantidos separados. Cada sessão é verificada no ambiente em que foi criada, e reembolsos e capturas vão para o ambiente do pagamento, mesmo que você altere o Test mode depois.
O reembolso falha com uma mensagem sobre o ambiente: o pagamento foi feito em UAT ou em produção, e nenhuma credencial desse ambiente está salva. Informe as credenciais e tente novamente.
Capture Windcave payment não aparece no bloco do pedido: o botão só é exibido para pedidos em Windcave payment on hold pagos com Auth que ainda não foram capturados ou liberados, e somente para funcionários autorizados a editar pedidos.
Onde encontrar detalhes: erros e avisos são sempre gravados no log; ative o Debug log para registrar também as requisições à API e os eventos de pagamento.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Windcave Payment Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Clean 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. As sessões, transações e reembolsos da Windcave e o status de pedido Windcave payment on hold são sempre mantidos, de modo que pedidos pagos antes ainda podem ser reembolsados e capturados depois de uma reinstalação. Os pedidos existentes mantêm suas observações de pagamento e IDs de transação.
A Windcave é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Windcave nem endossado por ela.