VibeFox Hubtel for WooCommerce — Ajuda

Requisitos

WordPress: 6.2 ou superior.

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

PHP: 8.0 ou superior.

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

Conta 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 estão no painel de controle 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 servidores autorizados. Solicite ao Hubtel (ao seu gerente de conta ou a support@hubtel.com) a inclusão do IP público do seu servidor web na lista de permissões. Até lá, os pagamentos não podem ser confirmados e os pedidos permanecem como Pagamento pendente.

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

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

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Hubtel > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira a sua chave de licença VibeFox no bloco de licença na parte superior da página e clique em Activate.

5. Insira o API ID, o API Key e o número da conta de comerciante (POS Sales ID).

6. Solicite ao suporte do Hubtel a inclusão do IP do seu servidor na lista de permissões para a Transaction Status API.

7. Ative Enable/Disable. A URL de callback é enviada ao Hubtel a cada pagamento, portanto não é necessário configurar nada no painel do Hubtel.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Hubtel. Acima dos campos, a página avisa quando o API ID, o API Key ou o número da conta de comerciante estiver faltando e quando a moeda da loja não for GHS. Em ambos os casos, o Hubtel fica oculto na finalização de compra. Ela também avisa se a loja estiver usando mais de 2 casas decimais. Na lista de métodos de pagamento, o gateway é sinalizado como necessitando de configuração até que as credenciais sejam preenchidas.

Enable/Disable: Enable Hubtel payments ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento exibido ao cliente na finalização de compra. Padrão: Mobile Money or card (Hubtel).

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. You will be redirected to Hubtel to complete the payment.

Credenciais de API do Hubtel

Copie o API ID e o API Key do painel de controle comercial do Hubtel: bo.hubtel.com > Programmable keys. O número da conta de comerciante é o POS Sales ID da sua conta 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): o API Key das suas chaves programáveis do Hubtel. Mantenha-o em sigilo.

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

Confirmação de pagamento

O callback avisa à sua loja que um pagamento foi realizado. A URL de callback exibida nesta seção é enviada ao Hubtel a cada pagamento, de modo que nada precisa ser configurado no painel do Hubtel. O formato é similar a https://your-site/wc-api/hubtel_pay/. Ela precisa ser acessível pela internet: sem modo de manutenção, proteção por senha ou firewall bloqueando o Hubtel.

Os callbacks do Hubtel não são assinados. O plugin obtém do callback apenas a referência de pagamento; essa referência deve pertencer a um pedido 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ó é marcado como pago depois que essa API confirmar o pagamento e o seu valor. Se o Hubtel não puder ser contatado, o pagamento é verificado novamente em segundo plano de forma automática, e você pode checá-lo na tela do pedido em Order actions > Check Hubtel payment status.

Avançado

Debug log: Log API calls and callbacks para WooCommerce > Status > Logs, fonte wcp_hubtel_pay, sem chaves ou dados dos clientes. Erros são sempre registrados. Padrão: desativado.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted (Hubtel data saved on orders is kept). Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Mobile Money or card (Hubtel)) e finaliza o pedido. O plugin cria um checkout no Hubtel para o total do pedido em GHS e direciona o cliente para a página de pagamento do Hubtel. O pagamento é exibido lá como Order #, o número do pedido e o nome do seu site. Na página do Hubtel o cliente paga com MTN MoMo, Telecel Cash, AirtelTigo Money, cartão Visa ou Mastercard ou GhQR. Cada clique em Place order ou Pay cria uma nova tentativa de pagamento com sua própria referência, e páginas mais antigas do Hubtel do mesmo pedido continuam disponíveis para pagamento.

Após o pagamento, o cliente retorna à página de pedido recebido. O pedido só é marcado como pago depois que o Hubtel o confirmar por meio da Transaction Status API: pelo callback, pela verificação efetuada quando o cliente retorna, por uma verificação em segundo plano ou pela ação do pedido. Um callback e um retorno que cheguem no mesmo instante são processados em sequência, para que o pedido nunca seja concluído duas vezes. Se o Hubtel ainda não tiver confirmado o pagamento, a página exibe 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. Se o pedido passou para Aguardando, exibe Your Hubtel payment was received and is being reviewed by the store. We will contact you if anything is needed.

Se o cliente clicar em Cancel na página do Hubtel, o plugin primeiro verifica se o pagamento foi concluído mesmo assim. Em caso negativo, o cliente volta para a página Pay for order com a mensagem The Hubtel payment was cancelled. You can try again or choose another payment method.

Se o Hubtel não conseguir iniciar o pagamento, o cliente vê 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, em caso de credenciais incorretas, Hubtel payments are not available at the moment. Please choose another payment method. Os detalhes são salvos 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. Ele é compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).

O plugin não oferece reembolsos pelo WooCommerce, não suporta assinaturas, cartões salvos nem seleção do canal de pagamento dentro do WooCommerce.

Pedidos

Status do pedido

Pending payment: o cliente foi enviado ao Hubtel e ainda não pagou, ou o Hubtel ainda não confirmou o pagamento.

Processing: o pagamento foi confirmado. Pedidos que contenham apenas produtos virtuais e baixáveis passam para Concluído, o padrão do WooCommerce. A nota do pedido mostra o valor, a transação do Hubtel, o método de pagamento e a referência. O ID da transação corresponde ao ID da transação do Hubtel.

On hold: o Hubtel informou um valor pago diferente do total do pedido, ou o pedido não está em GHS (nota Hubtel amount/currency mismatch); ou chegou um pagamento para um pedido que havia sido cancelado. O pedido não foi marcado como pago. Verifique o pagamento no painel do Hubtel e conclua ou reembolse o pedido manualmente.

Failed: o Hubtel informou que a última tentativa de pagamento de um pedido pendente falhou, e a Transaction Status API confirma que ele não está pago. O cliente pode tentar novamente a partir do pedido. Uma falha informada apenas por callback nunca faz um pedido passar para Malsucedido.

Se outra tentativa de um pedido que já está pago for paga também, o pedido não é alterado. Uma nota solicita que você reembolse a duplicata no seu painel do Hubtel. Um pedido cancelado ou reembolsado nunca é reaberto automaticamente. Quando o Hubtel informa um pagamento como reembolsado, uma nota é adicionada ao pedido.

Verificações de pagamento

Cerca de 20 minutos após o cliente ser enviado ao Hubtel, uma verificação em segundo plano (WooCommerce Action Scheduler) consulta o Hubtel sobre o pagamento, caso o callback tenha se perdido e o cliente não tenha retornado. Uma tentativa não paga é verificada mais uma vez após uma hora. Quando a API do Hubtel não puder ser acessada, a verificação é repetida até 5 vezes com intervalos progressivos.

A ação do pedido Check Hubtel payment status verifica as últimas tentativas do pedido (até 5, da mais recente para a mais antiga), aplica o resultado e adiciona uma nota com o status de cada tentativa.

Reembolsos

Reembolsos pelo WooCommerce não são suportados. Reembolse o pagamento no painel do Hubtel e depois crie um reembolso manual no WooCommerce.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica na parte superior de WooCommerce > Settings > Payments > Hubtel. 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 é válida 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 domínio. Remover a chave de um site não libera o seu espaço de domínio. Libere o espaço na sua conta do 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. 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 é exibido na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem uma renovação. O status é conferido novamente de forma automática em segundo plano.

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á ligado, se o API ID, o API Key e o número da conta de comerciante estão preenchidos e se a moeda é GHS. Na página Pay for order, vale a moeda do pedido. A página de configurações mostra um aviso se as credenciais ou a moeda estiverem incorretas.

O pagamento foi concluído, mas o pedido continua como Pagamento pendente: não foi possível confirmar o pagamento. Abra WooCommerce > Status > Logs, fonte wcp_hubtel_pay. Os códigos HTTP 401 ou 403 na verificação de status indicam que as chaves de API estão incorretas 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. Após corrigir, abra o pedido e execute Order actions > Check Hubtel payment status. As verificações em segundo plano também confirmam o pedido assim que o Hubtel responder.

O callback responde Unknown reference: a referência de pagamento não pertence a nenhum pedido desta loja.

O callback responde Payment status unavailable: a Transaction Status API não pôde ser contatada ou recusou a solicitação. O pagamento é verificado novamente em segundo plano.

O pedido está como Aguardando com uma nota de divergência de valor ou moeda: o Hubtel informou um valor pago diferente do total do pedido, ou o pedido não está em GHS. Verifique o pagamento no painel do Hubtel e conclua ou reembolse o pedido manualmente.

O cliente vê um erro ao finalizar o pedido: ative o Debug log e consulte o log. Chaves de API incorretas resultam em Hubtel payments are not available at the moment. Um problema de conexão resulta em Could not connect to Hubtel.

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 um espaço na sua conta do 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 contatado, o plugin continuará operando com o último status conhecido.

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

Desinstalação

Ao desativar o plugin, todos os dados são mantidos; apenas as verificações de pagamento pendentes em segundo plano são canceladas. Para removê-lo, desative e exclua o plugin na página Plugins. A chave de licença e o status da licença deste plugin são sempre excluídos. As configurações do gateway, as opções próprias do plugin, as verificações pendentes em segundo plano e os logs são removidos somente se Delete data on uninstall estava ativado. Caso contrário, permanecem para uma eventual reinstalação. Os dados do Hubtel salvos nos pedidos representam o histórico de pagamentos e são sempre mantidos. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.

O Hubtel é uma marca registrada de seu respectivo titular. Este plugin não é afiliado ao Hubtel nem endossado por ele.