VibeFox Windcave for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Conta 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 o de produção (sec.windcave.com). Peça-as ao suporte da Windcave ou ao seu gerente de conta. As chaves PxPay não funcionam com este plugin. Os métodos de pagamento que você quer oferecer (cartões, carteiras digitais e outros) precisam estar habilitados na sua conta Windcave.

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_windcave_payment_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Windcave > Manage, ou clique em Settings abaixo do nome do plugin na página 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 seu nome de usuário e sua chave da REST API: as credenciais UAT para o modo de teste e as de produção para pagamentos reais (veja Configuração).

6. Escolha o tipo de transação e os métodos de pagamento, ative Enable/Disable e salve. Faça um pagamento de teste com Test mode ativado e depois desative Test mode para receber pagamentos reais.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Windcave. Enquanto o modo de teste estiver ativado, a página mostra Test mode is on: payments go to the Windcave UAT environment and no real money is taken. Na lista de métodos de pagamento, a Windcave aparece como precisando de configuração até que o modo atual tenha um nome de usuário e uma chave de API. A versão do plugin aparece no final da página.

Geral

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ê na finalização de compra. Padrão: Credit/Debit Card (Windcave).

Description: o texto mostrado abaixo do método de pagamento na finalização de compra. Padrão: You will be redirected to the secure Windcave payment page to complete your payment.

Windcave REST API

Insira 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 de UAT podem ser salvas lado a lado. O modo de teste usa somente as credenciais UAT, e o modo real somente as de produção.

Test mode: Use the Windcave UAT test environment (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).

Pagamento

Transaction type: como o pagamento é cobrado. Padrão: Purchase.

Purchase (capture immediately): o dinheiro é cobrado quando o cliente paga.

Auth (authorise now, capture later): o dinheiro é apenas reservado. O pedido fica Aguardando, e você cobra o valor com Capture Windcave payment nas ações do pedido, ou libera a reserva ao reembolsar o valor total. Autorizações não capturadas expiram após alguns dias.

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. Eles precisam estar habilitados na sua conta Windcave. Deixe o campo vazio para exibir todos os métodos habilitados na conta. Padrão: Cards.

Avançado

Debug log: Log API requests and payment events. O log fica em WooCommerce > Status > Logs, origem wcp_windcave_payment_gateway. Erros e avisos são sempre registrados; esta opção acrescenta as requisições à API e os eventos de pagamento. As chaves de API, os dados do cartão e os dados pessoais dos clientes são mascarados. Padrão: desativado.

Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Os dados de pagamento salvos nos pedidos (os IDs de transação da Windcave necessários para reembolsos) são sempre mantidos. Padrão: desativado.

URL de notificação

Você não precisa configurar uma URL de notificação na Windcave. O plugin envia seus endereços de retorno e seu endereço de notificação em cada sessão de pagamento. A Windcave envia a notificação (Fail-Proof Result Notification) para https://your-site/wc-api/windcave_p_notification/. Nem o retorno do cliente nem a notificação são assinados pela Windcave, então o plugin nunca confia neles sozinhos: ele sempre lê o resultado da sessão pela REST API da Windcave, com as suas credenciais do ambiente em que a sessão foi criada.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Credit/Debit Card (Windcave)) e faz o pedido. O plugin cria uma sessão de pagamento da Windcave para o total do pedido na moeda do pedido e envia o cliente para a Windcave Hosted Payment Page. O número do pedido é enviado como referência do comerciante, junto com o idioma da loja e o nome, e-mail, telefone e endereços de cobrança e entrega do cliente. No modo de teste, o bloco de Finalização de compra mostra Test mode: payments go to the Windcave UAT environment, no real money is taken. abaixo do método de pagamento.

Após pagar, o cliente volta para a página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Windcave confirma: o plugin consulta a REST API da Windcave sobre o resultado da sessão, tanto quando o cliente retorna quanto quando chega a notificação da Windcave. Um bloqueio por pedido garante que o pagamento seja aplicado apenas uma vez. Se o resultado ainda não for conhecido, a página de pedido recebido verifica mais uma vez e 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.

Se o cliente voltar sem um pagamento concluído, a página de finalização de compra (ou a página Pay for order, se a tentativa começou ali) mostra uma destas mensagens:

Declined: seu pagamento foi recusado. Tente novamente ou escolha outro método de pagamento.

Cancelled or expired: o pagamento não foi concluído na página da Windcave. Seu pedido está salvo: você pode tentar novamente ou escolher outro método de pagamento.

Not confirmed yet: ainda não conseguimos confirmar seu pagamento. Se você concluiu o pagamento, não pague novamente: você receberá um e-mail de confirmação assim que a Windcave confirmar.

Return could not be processed: não conseguimos processar seu retorno da página de pagamento. Se você foi cobrado, entre em contato conosco antes de pagar novamente.

O carrinho não é esvaziado e o estoque não é reduzido antes que o cliente pague. Um cliente pode pagar novamente um pedido não pago, por exemplo pela página Pay for order. Uma nova tentativa verifica primeiro a sessão anterior: se ela já estiver paga, nenhum segundo pagamento é criado; se o cliente nunca usou a página de pagamento e o pedido 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 vê 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 é adicionado às notas do pedido. 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.

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 o WooCommerce High-Performance Order Storage (HPOS).

O plugin 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 taxas. Se a Windcave adicionar uma taxa, o pedido é conciliado com a transação principal.

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi enviado à Windcave e ainda não pagou, ou a Windcave ainda não confirmou o pagamento. Se o cliente cancelar ou a sessão expirar, o pedido continua como Pendente de pagamento e uma nota é adicionada.

Processing or Completed: um pagamento Purchase foi confirmado. O WooCommerce define o status como Processando, ou Concluído para pedidos que não precisam de envio, como de costume. A nota do pedido mostra o valor, o ID da transação da Windcave, o código de autorização, o tipo de cartão com o número mascarado e o ambiente (UAT ou produção). O ID da transação do pedido é o ID da transação da Windcave.

On hold (authorised): um pagamento Auth foi aprovado, mas ainda não capturado. A nota do pedido explica como capturá-lo ou liberá-lo.

On hold (does not match): a Windcave informou um valor, moeda, referência do comerciante ou tipo de transação diferente do pedido (por exemplo, o pedido foi editado depois que o pagamento começou). A nota lista as diferenças. Verifique o pagamento no Windcave Payline antes de enviar o pedido e reembolse-o, se necessário.

Failed: o pagamento foi recusado. A nota mostra o texto e o código de resposta da Windcave. O cliente pode tentar novamente.

Se chegar um pagamento aprovado para um pedido cancelado, ou um segundo pagamento aprovado para um pedido já pago, o pedido não é alterado. Uma nota com o ID da transação pede que você o reembolse no Windcave Payline (ou restaure o pedido cancelado manualmente).

Captura (modo Auth)

Abra o pedido, escolha Capture Windcave payment nas ações do pedido e clique no botão de atualizar. A ação aparece somente em um pedido Aguardando com uma autorização que ainda não foi capturada ou liberada. O valor total do pedido é capturado, a captura é adicionada às notas do pedido e o pedido segue como pedido pago (normalmente Processando). Se a Windcave não aceitar a captura, a tela do pedido mostra Windcave capture failed: com o motivo, e o motivo é adicionado às notas do pedido.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Windcave. Reembolsos totais e parciais são aceitos. O reembolso é enviado ao ambiente (UAT ou produção) e à conta em que o pagamento foi feito, por isso as credenciais desse ambiente precisam estar salvas. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID da transação da Windcave.

Para um pagamento Auth não capturado, só é possível um reembolso total: ele libera (anula) a autorização. Um valor parcial gera um erro pedindo que você reembolse o valor total ou capture o pagamento primeiro.

Se a Windcave recusar o reembolso, o WooCommerce mostra Windcave declined the refund: com o motivo, e nenhum reembolso é registrado. Se a Windcave ainda estiver processando o reembolso, o WooCommerce mostra Windcave has not confirmed the refund yet. See the order notes. e o reembolso não é registrado. Verifique a transação no Windcave Payline: se ela foi aprovada, registre o reembolso manualmente; caso contrário, tente novamente. Uma tentativa repetida do mesmo reembolso não é enviada duas vezes à Windcave. Reembolsos feitos no Windcave Payline não são informados à loja.

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 > Windcave. 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 o 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 a sua conta na vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere-a na sua conta vibefox.net.

Sem uma chave ativa, a Windcave 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. Gerentes da 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 Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e reembolsos e capturas 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

Windcave does not appear at 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, ou Production API username e Production API key no modo real.

The payment went through, but the order stays Pending payment: o plugin ainda não conseguiu obter o resultado da Windcave. Abra as notas do pedido: uma nota informa quando a sessão não pôde ser verificada e por quê. Confirme que as credenciais do ambiente do pagamento estão salvas e corretas. A verificação é repetida quando a Windcave envia a notificação novamente (o plugin responde com erro até que o resultado possa ser verificado, para que a Windcave tente de novo) e quando o cliente abre a página de pedido recebido. Seu servidor precisa aceitar as requisições da Windcave para https://your-site/wc-api/windcave_p_notification/.

Authentication failed in the order notes or the log: o nome de usuário ou a chave da REST API está errado, ou pertence ao outro ambiente. As credenciais UAT funcionam somente no modo de teste, e as de produção somente no modo real. As chaves PxPay não funcionam.

The customer sees that Windcave could not start the payment with the details of this order: a Windcave rejeitou a solicitação da sessão, por exemplo por causa da moeda ou de um método de pagamento não habilitado na sua conta. O motivo exato está nas notas do pedido e no log.

Order is On hold after payment: leia a nota do pedido. Ou o pagamento é um Auth aguardando captura, ou o valor pago, a moeda ou a referência do comerciante diferiam do pedido. Capture, envie ou reembolse o pagamento.

Test payments and live payments: UAT e produção são separados. Cada sessão é verificada no ambiente em que foi criada, e reembolsos e capturas vão para o ambiente do pagamento, mesmo se você alterar Test mode depois. Pedidos criados pela versão 1.0 do plugin usam o ambiente da antiga configuração API URL.

Refund fails with a message about the environment: o pagamento foi feito em UAT ou em produção, e não há credenciais salvas para esse ambiente. Informe-as e tente novamente.

Capture Windcave payment is missing in the order actions: a ação só é exibida para pedidos Aguardando pagos com Auth que ainda não foram capturados ou liberados.

Where to find details: erros e avisos são sempre gravados em WooCommerce > Status > Logs, origem wcp_windcave_payment_gateway. Ative Debug log para registrar também as requisições à API e os eventos de pagamento.

The license block shows an error: siga a mensagem exibida no 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 no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway, as opções do plugin e os logs (arquivos de log, inclusive os rotacionados, e entradas de log no banco de dados) são removidos somente se Clean uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e os IDs de transação da Windcave.

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