VibeFox Hubtel for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior com a extensão cURL. O módulo não é instalado sem elas.

Moeda: somente cedi ganês (GHS). O método de pagamento fica oculto na finalização de compra para outras moedas. Mantenha em 2 o número de casas decimais da moeda GHS, pois o Hubtel cobra pesewas inteiros.

Conta no Hubtel: uma conta comercial no Hubtel com chaves de API (API ID e API Key) e o número da conta de comerciante (POS Sales ID). As chaves ficam no painel comercial do Hubtel em bo.hubtel.com, em Programmable keys.

Lista de permissões de IP: o Hubtel responde à sua Transaction Status API somente a partir de endereços IP de servidor incluídos na lista de permissões. Peça ao Hubtel (seu gerente de conta ou support@hubtel.com) que inclua na lista de permissões o endereço IP público do seu servidor web. Até lá, os pagamentos não podem ser confirmados e nenhum pedido é criado.

Sem ambiente de teste: o Hubtel não possui sandbox público. Todos os pagamentos são reais.

Cron: recomenda-se uma tarefa cron no servidor que chame a URL cron do módulo a cada 5 minutos para as verificações de pagamento em segundo plano (veja Configuração).

Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um 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, mais tarde, encontre VibeFox Hubtel Pay Gateway na lista de módulos e clique em Configure.

3. Informe sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).

4. Informe o API ID, a API Key e o número da conta de comerciante (POS Sales ID).

5. Peça ao suporte do Hubtel que inclua o IP do seu servidor na lista de permissões da Transaction Status API.

6. Adicione ao cron do seu servidor a URL cron exibida na página Configure.

7. Ative Enable/Disable e clique em Save. A URL de callback é enviada ao Hubtel com cada pagamento, portanto nada precisa ser configurado no painel do Hubtel.

Na instalação, o módulo cria o status de pedido Hubtel payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Hubtel Pay Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando o API ID, a API Key ou o número da conta de comerciante estão ausentes e quando a moeda padrão da loja não é GHS. Nos dois casos, o Hubtel fica oculto na finalização de compra. Ela também avisa quando a moeda GHS usa mais de 2 casas decimais.

Hubtel

Enable/Disable: Enable Hubtel 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. Também é o nome do método de pagamento salvo no pedido. Padrão: Mobile Money or card (Hubtel). Obrigatório: um título vazio gera o erro Enter a title for the payment method.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with MTN MoMo, Telecel Cash, AirtelTigo Money or a Visa/Mastercard card. Você será redirecionado ao Hubtel para concluir o pagamento.

Credenciais da API do Hubtel

Copie o API ID e a API Key do seu painel comercial do Hubtel: bo.hubtel.com > Programmable keys. O número da conta de comerciante é o POS Sales ID da sua conta no Hubtel. A seção também repete o aviso sobre a lista de permissões de IP.

API ID (Client ID): o API ID das suas chaves programáveis do Hubtel.

API Key (Client Secret): a API Key das suas chaves programáveis do Hubtel. Mantenha-a em sigilo. A chave salva nunca é exibida novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-la.

Merchant account number (POS Sales ID): os pagamentos são recebidos nesta conta do Hubtel e conferidos com ela.

Clear saved API Key: marque a caixa e clique em Save para remover a API Key salva. Um campo vazio mantém o valor salvo.

Confirmação de pagamento

Callback URL: o callback informa à sua loja que um pagamento foi feito. Esta URL é enviada ao Hubtel com cada pagamento, portanto nada precisa ser configurado no painel do Hubtel. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_hubtel_pay/callback, possivelmente com um código de idioma. Precisa estar acessível pela internet: sem proteção por senha nem firewall bloqueando o Hubtel. O callback também funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

Os callbacks do Hubtel não são assinados. O módulo usa do callback somente a referência do pagamento; a referência deve pertencer a um pagamento da sua loja. O status, o valor e o ID da transação sempre vêm da Transaction Status API do Hubtel. O pedido só é criado como pago depois que essa API confirma o pagamento e o valor.

Verificações de pagamento em segundo plano (cron): a URL cron com um token secreto. Chame-a a cada 5 minutos a partir do cron do seu servidor, por exemplo com curl. Pagamentos sem confirmação são então reverificados automaticamente com o Hubtel: 20 minutos depois que o cliente foi enviado ao Hubtel, mais uma vez após uma hora se o pagamento ainda estiver não pago, e até 5 vezes com intervalos crescentes quando o Hubtel não pôde ser contatado. Mantenha a URL em sigilo.

Avançado

Debug log: registra chamadas à API e callbacks em logs/hubtel_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados dos clientes não são registrados. Erros e avisos são sempre registrados, mesmo quando esta opção está desativada. Padrão: desativado.

Log: mostra o tamanho atual 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 e o log deste módulo. Os dados do Hubtel salvos para os pedidos e o status de pedido Hubtel payment on hold sempre permanecem. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Mobile Money or card (Hubtel)) e confirma. O módulo cria uma finalização de compra no Hubtel para o total do carrinho em GHS e envia o cliente para a página de pagamento do Hubtel. O pagamento aparece lá como Cart #, o número do carrinho e o nome da sua loja. Na página do Hubtel, o cliente paga com MTN MoMo, Telecel Cash, AirtelTigo Money, cartão Visa ou Mastercard ou GhQR. Nesse ponto, ainda não existe pedido. Cada confirmação na etapa de pagamento cria uma nova tentativa de pagamento com sua própria referência, e as páginas anteriores do Hubtel do mesmo carrinho continuam aceitando pagamento.

Depois de pagar, o cliente retorna à sua loja. O pedido só é marcado como pago quando o Hubtel confirma por meio da Transaction Status API: pelo callback, pela verificação feita no retorno do cliente, por uma verificação em segundo plano ou pelo botão na página do pedido. Um callback e um retorno que chegam ao mesmo tempo são tratados um após o outro, de modo que o pedido nunca é criado duas vezes. Em seguida, o cliente vê a página padrão de confirmação do pedido. Se o pedido tiver sido colocado em espera, a página mostra Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Se o Hubtel ainda não tiver confirmado o pagamento quando o cliente retornar, aparece uma página Payment confirmation com a mensagem We are waiting for Hubtel to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. e os botões Check again e Back to checkout. O pedido é criado assim que o Hubtel confirma o pagamento. Se o Hubtel já tiver informado que esta tentativa de pagamento falhou, o cliente volta à finalização de compra com The Hubtel payment was not completed. You can try again or choose another payment method. O carrinho é mantido.

Se o cliente clicar em Cancel na página do Hubtel, o módulo primeiro verifica se o pagamento foi feito mesmo assim. Se não, o cliente volta à finalização de compra com The Hubtel payment was cancelled. You can try again or choose another payment method. O carrinho é mantido. Um pagamento posterior feito pela página cancelada do Hubtel continua sendo aceito.

Se o Hubtel não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Could not connect to Hubtel. Please try again in a moment., Hubtel could not start the payment. Please try again or choose another payment method. ou, com credenciais incorretas, Hubtel payments are not available at the moment. Please choose another payment method. Os detalhes vão para o log.

O módulo não oferece reembolsos pelo PrestaShop, não suporta assinaturas, cartões salvos nem a escolha do canal de pagamento dentro da loja.

Pedidos

Status do pedido

No order yet: o cliente foi enviado ao Hubtel e não pagou, ou o Hubtel ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: o pagamento foi confirmado pelo valor total exato do carrinho em GHS. O pagamento é registrado com o ID da transação do Hubtel, e uma nota mostra o valor, a transação do Hubtel, o método de pagamento e a referência.

Hubtel payment on hold: o Hubtel informou um valor pago diferente do total do carrinho, ou o carrinho não está em GHS. O pedido não foi marcado como pago; o valor que o Hubtel efetivamente cobrou é registrado como pagamento, e uma nota explica a divergência. Confira o pagamento no painel do Hubtel e processe o pedido ou reembolse-o manualmente. Se outra tentativa do mesmo carrinho for paga depois, pelo valor correto, o pedido passa para Payment accepted.

Se outra tentativa de um pedido já pago também for paga, o pedido não muda. Uma nota pede que você reembolse o duplicado no seu painel do Hubtel. Um pagamento de um pedido cancelado ou reembolsado adiciona uma nota, e o pedido nunca é reaberto automaticamente. Quando o Hubtel informa que um pagamento foi reembolsado, uma nota é adicionada ao pedido.

Bloco de pagamento do Hubtel

A página do pedido mostra um bloco Hubtel payment com todas as tentativas de pagamento do carrinho do pedido: data, referência, página de pagamento do Hubtel, valor, status no Hubtel, transação e resultado. Abaixo das tentativas, lista as Hubtel notes do pedido, da mais recente para a mais antiga.

O botão Check Hubtel payment status verifica as tentativas mais recentes do pedido (até 5, da mais recente para a mais antiga, parando assim que o pedido estiver pago), aplica o resultado e adiciona uma nota com o status de cada tentativa. O resultado é mostrado no bloco. É preciso ter permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. O botão fica disponível quando o pedido existe. Um carrinho pago sem pedido é confirmado pelo callback, pelo retorno do cliente ou pelo cron.

Reembolsos

Reembolsos pelo PrestaShop não são suportados. Reembolse o pagamento no painel do Hubtel e, em seguida, registre o reembolso no PrestaShop. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pelo Hubtel.

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 Hubtel Pay Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Hubtel Pay 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 ficam a linha Product: presta-payment-hubtel 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 for alterado, 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 domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a sua vaga de domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, o Hubtel não é exibido 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. A loja do PrestaShop não sabe que você está conectado ao back office, então a forma de pagamento também fica oculta para você: é possível configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização de compra. 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 também pelas verificações de pagamento em segundo plano.

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 inserida, depois uma vez por semana. Nenhum cron job é necessário para a verificação da licença. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.

Solução de problemas

O Hubtel não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o API ID, a API Key e o número da conta de comerciante estão preenchidos e se a moeda do carrinho é GHS. Em Payment > Preferences, verifique se o módulo está permitido para GHS, para o país do cliente e para o grupo do cliente. A página de configurações exibe um aviso quando as credenciais ou a moeda estão incorretas.

O pagamento foi feito, mas nenhum pedido foi criado: o pagamento não pôde ser confirmado. Ative Debug log e veja o campo Log na página do módulo. HTTP 401 ou 403 na verificação de status significa que as chaves de API estão erradas ou que o IP do servidor não está na lista de permissões do Hubtel. Verifique também se a URL de callback está acessível pela internet e se a URL cron está sendo chamada. Assim que o Hubtel responder, o próximo callback, a próxima verificação em segundo plano ou o próximo retorno do cliente criará o pedido.

O callback responde Unknown reference: a referência do pagamento não pertence a um pagamento desta loja.

O callback responde Payment status unavailable: a Transaction Status API não pôde ser acessada ou recusou a solicitação, ou o carrinho estava sendo confirmado por outra solicitação naquele mesmo momento. O pagamento é reverificado em segundo plano após 5 minutos.

O callback responde Gateway not configured: o API ID, a API Key ou o número da conta de comerciante está ausente. Preencha-os; o pagamento é reverificado em segundo plano.

O callback responde Invalid request ou Invalid ClientReference: a solicitação não continha um callback válido do Hubtel.

A URL de callback mostra Method not allowed no navegador: isso é normal. A URL aceita apenas solicitações do Hubtel.

A URL cron responde Forbidden: o token na URL está incorreto. Copie a URL cron exatamente como aparece nas configurações.

O pedido está como Hubtel payment on hold: leia as notas no bloco Hubtel payment (veja Status do pedido), confira o pagamento no painel do Hubtel e processe o pedido ou reembolse-o manualmente.

O cliente vê um erro ao escolher o Hubtel: ative Debug log e consulte o log. Chaves de API erradas geram Hubtel payments are not available at the moment. Um problema de conexão gera Could not connect to Hubtel. Um carrinho em outra moeda gera Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method.

Para desenvolvedores: o hook actionWcpHubtelPayIcon altera o ícone do método de pagamento, e o actionWcpHubtelPayPaymentDescription altera a descrição do pagamento na página do Hubtel (até 100 caracteres).

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Hubtel Pay 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 e o log deste módulo são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os dados do Hubtel salvos para os pedidos e o status de pedido Hubtel payment on hold sempre são mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

O Hubtel é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo Hubtel.