VibeFox HyperPay for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior com a extensão OpenSSL (ela descriptografa os webhooks). Sem ela, o módulo não pode ser instalado.

Conta na 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 (webhook key), 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 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 o VibeFox HyperPay Payment Gateway na lista de módulos e clique em Configure.

3. Informe 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 Access Token, o Entity ID e a chave de webhook de teste emitidos pela HyperPay e mantenha Test Mode ativado.

5. No painel da HyperPay (Administration > Webhooks), adicione um webhook de pagamento com a URL exibida na seção Webhook e copie a chave de descriptografia dele para o campo de chave de webhook do mesmo modo.

6. Ative Enable/Disable, clique em Save e faça um pagamento de teste com um cartão de teste da HyperPay. Depois, informe as credenciais de produção e desative Test Mode.

Na instalação, o módulo cria três status de pedido: Awaiting HyperPay payment, HyperPay payment authorized e HyperPay payment on hold. O PrestaShop vincula um novo módulo de pagamento às moedas, países e grupos de clientes ativos naquele momento. Países que você ativar depois precisam ser permitidos em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Test mode is on: payments go to the HyperPay test system and no real money is charged. enquanto o modo de teste estiver ativo. Ela avisa quando o Access Token ou o Entity ID do modo atual está ausente (o método de pagamento então não aparece na finalização da compra) e quando o modo atual não tem uma chave de webhook válida (os pagamentos então são confirmados apenas quando o cliente volta à loja). Ao salvar, os espaços são removidos das credenciais, e a página avisa se uma chave de webhook não for uma chave hexadecimal de 64 caracteres.

HyperPay

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 da compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Credit/Debit Card (HyperPay). Obrigatório.

Description: a descrição que o cliente vê na finalização da compra. Padrão: Pay securely using your credit or debit card.

Credenciais de API

O Access Token, o Entity ID e a chave de 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 de webhook é exibida no painel da HyperPay em Administration > Webhooks.

Test Mode: usa o sistema de teste 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. Enquanto estiver ativado, os clientes veem Test mode: no real payment will be made. abaixo do método de pagamento.

Test Access Token: o bearer token da sua conta de teste na 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 teste.

Live Access Token: o bearer token da sua conta de produção na 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.

Access tokens e chaves de webhook salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo.

Limpar segredos salvos: marque um token ou uma chave e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

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 exibida em Webhook URL nesta seção. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_hyperpay_payment_gateway/webhook, possivelmente com um código de idioma como /en/. Copie a URL exatamente como as configurações a mostram. 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 carrinhos, criada no mesmo modo da chave que a descriptografou. As notificações de teste da HyperPay são confirmadas. O webhook também informa capturas, estornos, reembolsos e chargebacks feitos no painel da HyperPay (veja Pedidos e reembolsos). Sem o webhook, um pagamento só é confirmado quando o cliente volta à loja depois de pagar.

Payment

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. Se nenhuma bandeira estiver marcada, a página avisa e o widget mostra VISA e Mastercard. Selecione somente 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 módulo não suporta.

Advanced

Enable Logging: registra as requisições e respostas da API em logs/hyperpay_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Os logs não contêm dados de cartão, chaves nem dados de clientes. Padrão: desativado.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Delete Data on Uninstall: quando ativado, desinstalar o módulo remove as configurações, a tabela de tentativas de pagamento da HyperPay e os arquivos de log. Pedidos e os status de pedido do módulo são mantidos. Padrão: desativado.

Finalização da compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Credit/Debit Card (HyperPay)) e confirma o pedido. O módulo prepara uma sessão de pagamento da HyperPay pelo total do carrinho na moeda do carrinho e abre a página HyperPay payment da sua loja com o widget da HyperPay e a mensagem Please complete your payment below:. O widget usa o idioma do cliente quando a HyperPay o oferece. No modo de teste, a página mostra Test mode: use a HyperPay test card, no real payment will be made. O cliente digita os dados do cartão no widget ou segue Choose another payment method para voltar à finalização da compra. Neste ponto, ainda não existe pedido. Recarregar a página reutiliza a mesma sessão de pagamento por até 25 minutos, enquanto o carrinho não mudar.

Depois de pagar, o cliente volta à sua loja. O módulo verifica se o pagamento pertence a uma sessão de pagamento deste carrinho e pede o resultado à HyperPay por uma requisição servidor a servidor, no modo em que a sessão foi criada. O pedido só é marcado como pago quando a HyperPay confirma: por essa requisição ou pelo webhook. O valor e a moeda devem corresponder aos do carrinho. Se o retorno e um webhook chegarem ao mesmo tempo, eles são tratados um após o outro, e o pedido nunca é criado duas vezes. Quando o pagamento é confirmado, o pedido é criado e o cliente vê a página padrão de confirmação do pedido.

Se o pagamento não foi concluído, o cliente volta à finalização da compra com uma mensagem: Payment failed: e o motivo informado pela HyperPay, Payment was not completed. Please try again., ou We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. O carrinho é mantido, e o cliente pode pagar de novo; cada nova tentativa recebe uma nova sessão de pagamento da HyperPay. Se o formulário de pagamento não puder ser preparado, o cliente permanece na finalização da compra com uma mensagem curta, por exemplo, informando que alguns dados de cobrança não foram aceitos pelo provedor de pagamento, ou que o formulário de pagamento não está disponível por causa de um erro de configuração de pagamento. O motivo técnico é registrado no log.

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 carrinho é arredondado para duas casas.

O webhook funciona com a loja em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

O módulo não oferece reembolsos ou anulações pelo PrestaShop, 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.

Pedidos e reembolsos

Status do pedido

No order yet: o cliente foi enviado à página de pagamento e não pagou, o pagamento foi recusado ou a HyperPay ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: um pagamento com débito foi confirmado, ou uma pré-autorização foi capturada. O pagamento é registrado com o ID do pagamento da HyperPay como ID da transação, e uma nota privada mostra o código de resultado da HyperPay, a descrição e o ID do pagamento. Se a HyperPay sinalizou o pagamento para análise manual, a nota informa isso; verifique-o no painel da HyperPay antes de enviar o pedido.

HyperPay payment authorized: o valor foi reservado por uma pré-autorização. Capture-o no bloco da HyperPay do pedido ou no painel da HyperPay; o webhook de captura então move o pedido para Payment accepted.

Awaiting HyperPay payment: a HyperPay informou que o pagamento está pendente. O pedido passa para Payment accepted quando a HyperPay confirma o pagamento.

HyperPay payment on hold: a HyperPay informou um valor ou uma moeda diferente dos do carrinho ou do pedido (por exemplo, o carrinho foi alterado depois que a página de pagamento foi aberta), ou o pagamento chegou depois que o pedido foi cancelado. A nota explica o caso. Verifique o pagamento no painel da HyperPay e depois atenda o pedido ou reembolse o pagamento.

Canceled: uma pré-autorização foi estornada no painel da HyperPay, e o webhook de estorno cancela o pedido autorizado.

Um resultado de recusa nunca altera um pedido existente. 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.

Bloco de pagamento da HyperPay

A página do pedido mostra um bloco HyperPay payment com o ID do pagamento (e o ID da captura, após uma captura), o tipo de transação, o ID da sessão de pagamento, o ID da transação do comerciante, o valor enviado à HyperPay, o resultado e um selo Test mode para pagamentos de teste. As notas do módulo ficam nas mensagens privadas do pedido.

Captura

Para um pedido em HyperPay payment authorized, o bloco mostra Capture payment com o valor. Clique e confirme Capture the pre-authorized amount through HyperPay?. O total atual do pedido é capturado, no modo em que a pré-autorização foi feita; por isso, o Access Token e o Entity ID desse modo precisam estar preenchidos. Você precisa da permissão para editar pedidos; o acesso às páginas do módulo não é necessário. Após uma captura bem-sucedida, o pedido passa para Payment accepted, e o ID da captura é adicionado ao pagamento e às notas. Se a HyperPay recusar a captura, o código de resultado e a descrição são exibidos e adicionados às notas, e o pedido permanece autorizado. Um clique duplo não captura duas vezes. A anulação (void) de uma pré-autorização é feita no painel da HyperPay.

Reembolsos

Reembolsos pelo PrestaShop não são suportados, e os botões padrão de reembolso do PrestaShop não devolvem dinheiro pela HyperPay. Reembolse o pagamento no painel da HyperPay e registre-o no PrestaShop com um reembolso parcial ou uma nota de crédito, se necessário. Reembolsos e chargebacks feitos na HyperPay são adicionados ao pedido como nota pelo webhook; o status do pedido não muda.

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 HyperPay Payment Gateway é o primeiro bloco em Modules > Module Manager > VibeFox HyperPay 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 aparecem a linha Product: presta-payment-hyperpay 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 do 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 HyperPay não é exibida aos clientes na finalização da compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A loja PrestaShop não sabe que você está conectado ao 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 na finalização da 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 as capturas e reembolsos funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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, 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 HyperPay não aparece na finalização da 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 ausentes. 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 concluído, mas nenhum pedido foi criado: 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 exibida em Webhook URL e se a chave de descriptografia está no campo de chave de webhook do mesmo modo. Ative Enable Logging e consulte o campo Log na página do módulo.

O webhook responde Decryption failed: a chave de webhook pertence a outro webhook ou a outro modo. Copie a chave novamente do painel da HyperPay.

O webhook responde Webhook key not configured: não há uma chave de webhook válida definida. Cole a chave de 64 caracteres nas configurações. A HyperPay repete o webhook.

O webhook responde Busy, retry later: o pedido estava sendo processado por outra requisição no mesmo instante, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A HyperPay repete o webhook. O motivo está no log.

O log mostra Webhook ignored: o pagamento não pertence a um carrinho desta loja, ou foi feito no outro modo. Pagamentos de teste e de produção são mantidos separados.

A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições POST da HyperPay.

O formulário de pagamento não carrega: consulte o log. Um erro de configuração geralmente indica Access Token ou Entity ID incorretos 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á em HyperPay payment on hold: leia as notas do pedido (veja Status do pedido), verifique o pagamento no painel da HyperPay e depois atenda o pedido ou reembolse o pagamento.

A captura falha: leia o código de resultado e a descrição no bloco e nas notas. A captura é enviada no modo da pré-autorização, por isso as credenciais desse modo precisam estar definidas; caso contrário, o bloco informa que o Access Token / Entity ID desse modo estão vazios.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox HyperPay Payment 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 ativado, as configurações, a tabela de tentativas de pagamento da HyperPay e os arquivos de log são removidos. Se estiver desativado, tudo é mantido para uma reinstalação posterior. Os status de pedido Awaiting HyperPay payment, HyperPay payment authorized e HyperPay payment on hold são sempre mantidos. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.

HyperPay é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela HyperPay.