VibeFox EveryPay for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo.

PHP: 8.0 ou superior.

Conta EveryPay: você precisa do nome de usuário da API, do segredo da API e do nome da conta de processamento da sua loja online. Eles estão no Merchant Portal da EveryPay, nas configurações da sua loja: o portal de demonstração (mwt-demo.every-pay.com) para o modo de teste e o portal de produção (portal.every-pay.eu) para pagamentos reais. Os ambientes de teste e de produção têm credenciais separadas. Você também configura a URL de callback da sua loja nos dois portais (veja Configuração).

Moeda da loja: a conta de processamento define a moeda cobrada; por exemplo, EUR3D1 cobra em EUR. O método de pagamento só é oferecido para pedidos nessa moeda.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_everypay_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > EveryPay > Manage, ou clique em Settings embaixo 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 o nome de usuário da API de teste, o segredo da API de teste e o nome da conta de processamento do Merchant Portal de demonstração. Mantenha Test Mode ativado.

6. Copie a URL de callback exibida na página de configurações para Callback notification URL da sua loja no Merchant Portal.

7. Ative Enable/Disable e faça um pedido de teste. Quando tudo estiver funcionando, insira as credenciais de produção, configure a URL de callback também no portal de produção e desmarque Test Mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > EveryPay. Acima dos campos, a página exibe Test mode is on: payments go to the EveryPay demo environment, no real money is charged. enquanto o modo de teste estiver ativo. Ela avisa quando o gateway está habilitado mas faltam o nome de usuário da API, o segredo da API ou a conta de processamento do modo atual (o método de pagamento fica então oculto na finalização de compra), e quando a conta de processamento cobra uma moeda diferente da moeda da loja. Na lista de métodos de pagamento, a EveryPay aparece como precisando de configuração até que o modo atual esteja configurado. Espaços e quebras de linha colados junto com as credenciais são removidos ao salvar.

Geral

Enable/Disable: Enable EveryPay payment gateway ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: EveryPay.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely by card or bank link on the EveryPay payment page.

Conta EveryPay

O nome de usuário da API, o segredo da API e o nome da conta de processamento aparecem no Merchant Portal da EveryPay (configurações da loja): o portal de demonstração para o modo de teste e o portal de produção para pagamentos reais.

Test Mode: Enable test mode envia os pagamentos para o ambiente de demonstração da EveryPay com as credenciais de teste. Nenhum dinheiro real é cobrado. Padrão: ativado.

Test API Username: o nome de usuário da API do ambiente de demonstração.

Test API Secret: o segredo da API do ambiente de demonstração.

Live API Username: o nome de usuário da API do ambiente de produção.

Live API Secret: o segredo da API do ambiente de produção.

Processing Account Name: a conta de processamento da EveryPay, por exemplo EUR3D1. A conta define a moeda cobrada: o gateway só é oferecido para pedidos nessa moeda. O mesmo nome de conta é usado nos dois modos.

Notificações de pagamento (callback)

O callback informa à sua loja que um pagamento foi finalizado, para que os pedidos sejam atualizados mesmo que o cliente feche o navegador. Copie a URL exibida nesta seção para Callback notification URL da sua loja no Merchant Portal da EveryPay, tanto na demonstração quanto na produção. A URL tem este formato: https://your-site/wc-api/wc_evp_payment/. A solicitação de pagamento não carrega uma URL de callback, por isso ela precisa ser configurada no portal.

O callback traz apenas referências de pagamento. Quando ele chega, o plugin consulta a API da EveryPay sobre o status do pagamento no ambiente em que o pagamento foi criado e verifica se a resposta pertence a este pedido. Callbacks de um pagamento que o pedido não criou são rejeitados. Sem o callback, um pedido é confirmado quando o cliente volta para a loja após pagar, ou quando você executa Check EveryPay payment status no pedido.

Avançado

Debug log: Log payment events grava os eventos de pagamento em WooCommerce > Status > Logs, origem wcp_everypay_payment. Os erros são sempre registrados. Segredos da API e dados de cartão nunca são registrados. Padrão: desativado.

Uninstall: Delete the gateway settings and logs when the plugin is deleted. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão, EveryPay) e faz o pedido. No modo de teste, a finalização de compra exibe TEST MODE: EveryPay demo environment, no real money is charged. O plugin cria um pagamento único da EveryPay pelo total do pedido, com o e-mail e os dados de cobrança do cliente, e envia o cliente para a página de pagamento da EveryPay. O idioma da página acompanha o idioma do site (inglês, estoniano, russo, letão, lituano, finlandês ou alemão; caso contrário, inglês). Lá o cliente paga com um dos métodos habilitados na sua conta EveryPay.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a EveryPay confirma: o plugin consulta a API da EveryPay sobre o status do pagamento no retorno e no callback. Um pedido pago, um pedido em análise ou um pagamento ainda em processamento leva à página de pedido recebido.

Se o pagamento falhar, o cliente volta para a finalização de compra (ou para a página Pay for order) com a mensagem Your EveryPay payment was not successful. Please try again or choose another payment method. Se o cliente saiu da página de pagamento sem pagar, a mensagem é The EveryPay payment was not completed. You can try again or choose another payment method. Cada nova tentativa cria um novo pagamento da EveryPay; as tentativas anteriores são registradas, de modo que um pagamento feito com um link antigo continua sendo reconhecido.

Se a EveryPay não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo EveryPay is temporarily unavailable. Please try again in a moment or choose another payment method. Os detalhes estão 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 o WooCommerce High-Performance Order Storage (HPOS). Os textos exibidos ao cliente estão traduzidos para o estoniano.

O plugin aceita apenas pagamentos únicos. Não há reembolsos ou capturas pelo WooCommerce, cartões salvos ou pagamentos com um clique, assinaturas ou pagamentos recorrentes, campos de cartão incorporados e nem múltiplas moedas.

Pedidos

Status do pedido

Pending payment: o cliente foi enviado para a EveryPay e ainda não pagou, ou o pagamento ainda está sendo processado.

Processing: a EveryPay informou que o pagamento foi liquidado ou autorizado (pedidos com apenas produtos virtuais baixáveis passam para Concluído, o padrão do WooCommerce). A nota do pedido mostra o valor, a moeda e a referência do pagamento. O ID da transação do pedido é a referência de pagamento da EveryPay. Em um pagamento autorizado, a nota informa que os valores estão reservados: se a sua conta não capturar automaticamente, capture o pagamento no Merchant Portal da EveryPay. Quando ele for liquidado depois, uma nota informa isso.

On hold after payment: o pagamento precisa de análise manual. O valor ou a moeda pagos diferem do pedido, o pedido foi cancelado antes de o pagamento chegar, ou o pedido agora usa outro método de pagamento. A nota explica isso e informa que o pedido não foi marcado como pago. Verifique o pagamento no Merchant Portal e conclua ou reembolse manualmente. Callbacks posteriores desse pagamento não concluem o pedido automaticamente.

Failed: a última tentativa de pagamento de um pedido não pago falhou, foi abandonada ou anulada. A nota mostra o motivo informado pela EveryPay. O cliente pode tentar novamente.

Se um segundo pagamento for concluído para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no Merchant Portal da EveryPay.

Check EveryPay payment status

Na tela do pedido, escolha a ação do pedido Check EveryPay payment status. O plugin verifica com a API cada pagamento da EveryPay do pedido, aplica o resultado conforme descrito acima e adiciona uma nota com o status de cada pagamento. Use-a para pedidos cujo callback nunca chegou.

Reembolsos

Reembolsos pelo WooCommerce não são suportados. Reembolse no Merchant Portal da EveryPay e depois altere o status do pedido no WooCommerce. Quando a EveryPay informa que um pagamento foi reembolsado ou sofreu chargeback, o plugin apenas adiciona uma nota ao pedido; o status do pedido não muda.

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 > EveryPay. 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 no vibefox.net.

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

Sem uma chave ativa, a EveryPay 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. Os gerentes da 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 Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados e a verificação de status funciona.

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 EveryPay não aparece na finalização de compra: confira se a licença está ativa, se Enable/Disable está ativado, se o nome de usuário da API, o segredo da API e o Processing Account Name do modo atual estão preenchidos, e se a moeda da loja (na página Pay for order, a moeda do pedido) é a moeda da conta de processamento. A página de configurações exibe um aviso nesses casos.

O pagamento foi feito, mas o pedido continua em Pending payment: o callback não está funcionando. Confira se a URL de callback das configurações está definida como Callback notification URL no Merchant Portal do modo que você usa (demonstração ou produção). Você também pode abrir o pedido e executar Check EveryPay payment status. Ative o Debug log e veja em WooCommerce > Status > Logs, origem wcp_everypay_payment.

O callback responde Unknown payment reference ou Payment does not belong to this order: o pagamento não foi criado por este pedido, ou a resposta da EveryPay não corresponde a ele. O pedido não é alterado.

O callback responde Not configured: faltam as credenciais do ambiente em que o pagamento foi criado, por exemplo um pagamento de teste depois que as credenciais de teste foram removidas. Insira-as novamente; a EveryPay repete o callback.

O callback responde Payment status unavailable ou Busy, please retry: a API da EveryPay não pôde ser acessada, ou o pedido estava sendo atualizado por outra requisição no mesmo momento. A EveryPay repete o callback.

O cliente vê EveryPay is temporarily unavailable: a EveryPay recusou as credenciais ou não pôde ser acessada. Confira o nome de usuário da API e o segredo da API do modo atual.

O cliente vê This payment method does not support the order currency: a moeda do pedido é diferente da moeda da conta de processamento.

O pedido está On hold after payment: leia a nota do pedido. O valor ou a moeda eram diferentes, ou o pedido foi cancelado antes de o pagamento chegar. Verifique o pagamento no Merchant Portal e conclua ou reembolse manualmente.

O bloco de licença mostra um erro: 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 no 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 wc_evp_icon, wc_evp_locale, wc_evp_currency_decimals e wc_evp_oneoff_request.

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 e os logs só são removidos se a opção Uninstall (Delete the gateway settings and logs when the plugin is deleted) estiver ativada. Caso contrário, eles permanecem para uma reinstalação posterior. As referências de pagamento da EveryPay armazenadas nos pedidos são sempre mantidas. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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