VibeFox HyperPay for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
Conta HyperPay: a HyperPay emite o Access Token e o Entity ID quando sua conta de comerciante é configurada. As credenciais de teste e de produção são diferentes. Você também precisa de um webhook de pagamento no painel da HyperPay e da sua chave de descriptografia (chave do webhook), exibida em Administration > Webhooks (veja Configuração).
Dados do cartão: o cartão é digitado somente no widget da HyperPay, então os dados do cartão nunca chegam ao seu servidor (PCI DSS SAQ A).
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_hyperpay_payment_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > HyperPay > Manage, ou clique em Settings abaixo do nome do plugin na página de plugins.
4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Digite o Access Token, o Entity ID e a chave do webhook de teste emitidos pela HyperPay e mantenha Test Mode ativado.
6. No painel da HyperPay (Administration > Webhooks), adicione um webhook de pagamento com a URL mostrada nas configurações e copie a chave de descriptografia dele para o campo de chave do webhook do mesmo modo.
7. Ative Enable/Disable e faça um pagamento de teste com um cartão de teste da HyperPay. Depois, digite as credenciais de produção e desative Test Mode.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > HyperPay. Acima dos campos, a página mostra O modo de teste está ativado: os pagamentos vão para o sistema de testes da HyperPay e nenhum dinheiro real é cobrado. enquanto o modo de teste estiver ativado. Ela avisa quando faltam o Access Token ou o Entity ID do modo atual (nesse caso, o método de pagamento não aparece na finalização de compra) e quando o modo atual não tem uma chave de webhook válida (nesse caso, os pagamentos só são confirmados quando o cliente volta à loja). Na lista de métodos de pagamento, o gateway aparece como precisando de configuração até que o modo atual tenha seu Access Token e Entity ID. Ao salvar, os espaços são removidos das credenciais, e a página mostra um erro se uma chave de webhook não for uma chave hexadecimal de 64 caracteres.
Enable/Disable: Enable HyperPay Payment ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o título que o cliente vê na finalização de compra. Padrão: Credit/Debit Card (HyperPay).
Description: a descrição que o cliente vê na finalização de compra. Padrão: Pay securely using your credit or debit card.
Credenciais de API
O Access Token, o Entity ID e a chave do webhook são emitidos pela HyperPay quando sua conta de comerciante é configurada. As credenciais de teste e de produção são diferentes. A chave do webhook aparece no painel da HyperPay em Administration > Webhooks.
Test Mode: Enable Test Mode usa o sistema de testes da HyperPay (eu-test.oppwa.com) e as credenciais de teste. Nenhum dinheiro real é cobrado. Desative para aceitar pagamentos reais com as credenciais de produção (eu-prod.oppwa.com). Padrão: ativado.
Test Access Token: o bearer token da sua conta de teste da HyperPay.
Test Entity ID: o Entity ID do canal de pagamento de teste.
Test Webhook Key: a chave hexadecimal de 64 caracteres usada para descriptografar as notificações de webhook do sistema de testes.
Live Access Token: o bearer token da sua conta de produção da HyperPay.
Live Entity ID: o Entity ID do canal de pagamento de produção.
Live Webhook Key: a chave hexadecimal de 64 caracteres usada para descriptografar as notificações de webhook do sistema de produção.
Webhook
O webhook informa sua loja sobre os pagamentos mesmo quando o cliente fecha o navegador antes de voltar à loja. No painel da HyperPay (Administration > Webhooks), adicione um webhook para pagamentos com a URL mostrada nesta seção das configurações. Ela tem este formato: https://your-site/wp-json/hyperpay-p/v1/webhook. Depois, copie a chave de descriptografia do webhook para Test Webhook Key ou Live Webhook Key, conforme o mesmo modo.
Os webhooks da HyperPay são criptografados (AES-256-GCM). Um webhook que não pode ser descriptografado com suas chaves é rejeitado. Somente as notificações de pagamento são processadas, e o pagamento precisa pertencer a uma sessão de pagamento de um dos seus pedidos, criada no mesmo modo da chave que o descriptografou. As notificações de teste da HyperPay são confirmadas. O webhook também informa capturas, reversões, reembolsos e contestações feitos no painel da HyperPay (veja Pedidos e reembolsos). Sem o webhook, um pagamento só é confirmado quando o cliente volta à loja depois de pagar.
Pagamento
Transaction Type: como o cartão é cobrado.
Payment Brands: as bandeiras exibidas no widget de pagamento: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. Padrão: VISA e Mastercard. Selecione apenas as bandeiras que a HyperPay habilitou para o seu Entity ID; mada, STC Pay e Apple Pay costumam usar uma entidade própria, que este plugin não suporta.
Avançado
Enable Logging: Log API requests and responses. As informações de depuração são gravadas em WooCommerce > Status > Logs, origem wcp_hyperpay_payment_gateway. Erros são sempre registrados. Os logs não contêm dados de cartão, chaves ou dados do cliente. Padrão: desativado.
Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Remove as configurações e os arquivos de log quando o plugin é excluído. Os dados da HyperPay salvos nos pedidos são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Credit/Debit Card (HyperPay)) e clica em Continue to payment. O pedido é criado e o cliente vai para a página Pay for order. Ali, o plugin prepara uma sessão de pagamento da HyperPay para o total do pedido na moeda do pedido e mostra o widget da HyperPay com a mensagem Conclua seu pagamento abaixo:. O widget usa o idioma do seu site quando a HyperPay o suporta. No modo de teste, a página mostra Modo de teste: use um cartão de teste da HyperPay; nenhum pagamento real será feito. O cliente digita os dados do cartão no widget.
Depois de pagar, o cliente volta à sua loja. O plugin confere se o pagamento pertence a uma das sessões de pagamento deste pedido e pede o resultado à HyperPay por uma consulta servidor a servidor. O pedido só é marcado como pago depois que a HyperPay confirma: por essa consulta ou pelo webhook. O valor e a moeda precisam corresponder ao pedido. Um retorno e um webhook que chegam ao mesmo tempo são tratados um após o outro, de modo que o pedido nunca é processado duas vezes. Quando o pagamento é confirmado, o cliente é direcionado para a página de pedido recebido.
Se o pagamento não foi concluído, o cliente volta à página Pay for order com uma mensagem: Falha no pagamento: e o motivo informado pela HyperPay, O pagamento não foi concluído. Tente novamente., ou Ainda não foi possível confirmar seu pagamento. Se você foi cobrado, o pedido será atualizado automaticamente; caso contrário, tente novamente. O cliente pode pagar de novo na mesma página. Se o widget não puder ser preparado, o cliente vê uma mensagem curta, por exemplo que alguns dados de cobrança não foram aceitos pelo provedor de pagamento, e um botão Try Again. Os detalhes são adicionados às notas do pedido.
Os valores são enviados com duas casas decimais, como exige a API da HyperPay. Em moedas com 3 casas decimais (KWD, BHD, JOD, OMR), o total do pedido é arredondado para duas casas decimais.
O método de pagamento funciona na finalização de compra clássica, nos blocos de Carrinho e de Finalização de compra e na página Pay for order. No modo de teste, o bloco de Finalização de compra mostra Modo de teste: nenhum pagamento real será feito. É compatível com o HPOS (High-Performance Order Storage) do WooCommerce.
O plugin não oferece reembolsos ou anulações pelo WooCommerce, cartões salvos ou tokenização, assinaturas, verificação de domínio do Apple Pay, uma entidade separada por bandeira nem Tabby, Tamara ou outros métodos de compre agora e pague depois (buy now, pay later).
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente ainda não pagou, não concluiu o widget ou a HyperPay ainda não confirmou o pagamento.
Processing: um pagamento com débito foi confirmado, ou uma pré-autorização foi capturada. Pedidos com apenas produtos virtuais para download passam para Concluído, o padrão do WooCommerce. A nota do pedido mostra o código de resultado da HyperPay, a descrição e o ID do pagamento. O ID da transação é o ID do pagamento na HyperPay. Se a HyperPay sinalizou o pagamento para análise manual, a nota informa isso; verifique no painel da HyperPay antes de enviar.
On hold (pre-authorization): o valor foi reservado. Capture-o com a ação do pedido Capture HyperPay payment ou no painel da HyperPay; o webhook de captura então conclui o pedido.
On hold after payment: a HyperPay informou um valor ou moeda diferente do pedido (por exemplo, porque o pedido foi editado depois que a página de pagamento foi aberta), o pagamento ainda está pendente na HyperPay, ou o pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica. Verifique o pagamento no painel da HyperPay e conclua-o ou reembolse-o.
Failed: a HyperPay recusou o pagamento. O motivo está na nota do pedido e é mostrado ao cliente. Uma tentativa recusada nunca altera um pedido que já está pago, reservado, em espera ou cancelado.
Cancelled: uma pré-autorização foi revertida no painel da HyperPay, e o webhook de reversão cancela o pedido em espera.
Se chegar outro pagamento bem-sucedido para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse a duplicata no painel da HyperPay. Um pagamento bem-sucedido para um pedido reembolsado apenas acrescenta uma nota.
Captura
A ação do pedido Capture HyperPay payment aparece em pedidos Em espera com uma pré-autorização que ainda não foi capturada. Ela captura o total atual do pedido, menos os reembolsos já registrados no WooCommerce, no modo em que a pré-autorização foi feita. Após uma captura bem-sucedida, o pedido passa para Em andamento. Se a HyperPay recusar a captura, o código de resultado e a descrição são exibidos e adicionados às notas do pedido. A anulação (void) de uma pré-autorização é feita no painel da HyperPay.
Reembolsos
Reembolsos pelo WooCommerce não são suportados. Reembolse o pagamento no painel da HyperPay e registre-o no WooCommerce com Refund manually. Reembolsos e contestações feitos na HyperPay são adicionados ao pedido como nota pelo webhook; 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 > HyperPay. 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 digitar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta na 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 na sua conta na vibefox.net.
Sem uma chave ativa, a HyperPay não é exibida aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê Este método de pagamento não está disponível. Escolha outro. Os gerentes da loja conectados continuam vendo o método de pagamento, marcado como (unlicensed — visible to admins only), para que possam 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 as 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
A HyperPay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo atual tem seu Access Token e Entity ID: os de teste no modo de teste, os de produção no modo de produção. A página de configurações mostra um aviso quando eles estão faltando.
O pagamento foi feito, mas o pedido continua como Pending payment: o webhook não está funcionando e o cliente não voltou à loja. No painel da HyperPay, verifique se o webhook de pagamento existe para o modo que você usa, se a URL dele é exatamente a mostrada nas configurações e se a chave de descriptografia está no campo de chave do webhook do mesmo modo. Veja WooCommerce > Status > Logs, origem wcp_hyperpay_payment_gateway.
O webhook responde Decryption failed: a chave do webhook pertence a outro webhook ou a outro modo. Copie a chave novamente do painel da HyperPay.
O webhook responde Webhook key not configured: nenhuma chave de webhook válida está definida. Cole a chave de 64 caracteres nas configurações. A HyperPay tenta o webhook novamente.
O log mostra Webhook ignored: o pagamento não pertence a um pedido desta loja, ou foi feito no outro modo. Pagamentos de teste e de produção são mantidos separados.
O formulário de pagamento não carrega: leia a nota do pedido. Um erro de configuração geralmente significa um Access Token ou Entity ID incorreto para o modo atual. Uma mensagem sobre dados de cobrança significa que a HyperPay não aceitou alguns dados do cliente. Verifique se as Payment Brands selecionadas estão habilitadas para o seu Entity ID.
O pedido está On hold com uma nota de divergência de valor ou moeda: a HyperPay informou um pagamento que não corresponde ao total ou à moeda do pedido, por exemplo porque o pedido foi editado depois que a página de pagamento foi aberta. Verifique o pagamento no painel da HyperPay e conclua-o ou reembolse-o.
A captura falha: leia o código de resultado e a descrição na nota do pedido. A captura é enviada no modo da pré-autorização, então as credenciais desse modo precisam estar configuradas.
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 na 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: o filtro hyperpay_p_icon altera o ícone do método de pagamento.
Desinstalação
Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway, os dados temporários do plugin e os arquivos de log são removidos somente se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os dados da HyperPay salvos nos pedidos são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
HyperPay é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela HyperPay.