VibeFox Hubtel for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado com 3.0.5.0) ou 4.0.2 e superior (testado com 4.1.0.3).

PHP: 8.0 ou posterior com a extensão cURL.

Moeda: apenas cedi ganês (GHS). O método de pagamento fica oculto na finalização de compra quando a moeda do pedido não é GHS. Mantenha em 2 o número de casas decimais da moeda GHS, porque a Hubtel cobra pesewas inteiros.

Conta na Hubtel: uma conta empresarial na 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 empresarial da Hubtel em bo.hubtel.com, em Programmable keys.

Lista de IPs permitidos: a Hubtel responde à sua Transaction Status API apenas a partir de endereços IP de servidores incluídos na lista de permitidos. Peça à Hubtel (seu gerente de conta ou support@hubtel.com) para incluir na lista o endereço IP público do seu servidor web. Até lá, os pagamentos não podem ser confirmados e os pedidos permanecem sem status.

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

Cron: recomenda-se uma tarefa cron no seu servidor que chame a URL cron da extensão a cada 5 minutos, para as verificações de pagamento em segundo plano (veja Configuration).

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

O download é um único arquivo zip com os pacotes das duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 wcp_hubtel_pay-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_hubtel_pay.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No painel administrativo, vá até Extensions > Installer, clique em Upload e escolha o arquivo wcp_hubtel_pay-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então não é preciso atualizar Extensions > Modifications. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá até Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Hubtel Pay Gateway e clique em Install (o botão verde +). Seu usuário administrador precisa ter o direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja License key).

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

5. Peça ao suporte da Hubtel para incluir na lista de permitidos o IP do seu servidor para a Transaction Status API.

6. Adicione ao cron do seu servidor a URL cron exibida na seção Payment confirmation.

7. Ative Enable/Disable e clique em Save. A URL de callback é enviada à Hubtel com cada pagamento, então não é preciso configurar nada no painel da Hubtel.

OpenCart 4

1. No painel administrativo, vá até Extensions > Installer, clique em Upload e escolha o arquivo wcp_hubtel_pay.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Vá até Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Hubtel Pay Gateway, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença, as credenciais da Hubtel e o cron como nos passos 3 a 7 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a URL de callback e a URL do cron são diferentes (veja Payment confirmation).

Uma instalação nova começa com o método de pagamento desativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Hubtel Pay Gateway > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando o API ID, a API Key ou o número da conta de comerciante estão faltando, e quando a moeda padrão da loja não é GHS. Nos dois casos, a Hubtel fica oculta na finalização de compra. A página também avisa quando a moeda GHS usa mais de 2 casas decimais (defina isso em System > Localisation > Currencies). Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode estar vazio e deve ter no máximo 128 caracteres (Enter a title for the payment method (1 to 128 characters).), Sort Order deve ser um número inteiro, Total um número igual ou maior que 0, e a geo zone e os status de pedido precisam existir; caso contrário, nada é salvo. Se o método de pagamento for ativado sem as credenciais, as configurações são salvas com um aviso.

Hubtel

Enable/Disable: Enable Hubtel payments liga ou desliga o método de pagamento. Padrão: desligado.

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.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação, ao lado do ícone de Mobile Money e cartão. 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.

Sort Order: a posição da Hubtel entre os métodos de pagamento na finalização de compra. Deixe em branco ou digite um número inteiro.

Geo Zone: ofereça a Hubtel apenas para endereços de pagamento da geo zone selecionada. Padrão: All zones. As geo zones são configuradas em System > Localisation > Geo Zones.

Total: o valor total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir antes que a Hubtel seja oferecida. Deixe em branco para não ter valor mínimo.

Credenciais de API da Hubtel

Copie o API ID e a API Key do seu painel empresarial da Hubtel: bo.hubtel.com > Programmable keys (a seção traz um link para lá). O número da conta de comerciante é o POS Sales ID da sua conta na Hubtel. A seção também repete o aviso sobre a lista de IPs permitidos.

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

API Key (Client Secret): a API Key das suas chaves programáveis da 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 apenas se quiser alterá-lo. Para remover a chave salva, marque Clear saved API Key abaixo do campo e clique em Save.

Número da conta de comerciante (POS Sales ID): os pagamentos são recebidos nesta conta da Hubtel e conferidos com ela.

Confirmação de pagamento

Callback URL: o callback informa à sua loja que um pagamento foi feito. Esta URL é enviada à Hubtel com cada pagamento, então não é preciso configurar nada no painel da Hubtel. No OpenCart 3 ela tem o formato https://your-store/index.php?route=extension/payment/wcp_hubtel_pay/callback, e no OpenCart 4 https://your-store/index.php?route=extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.callback. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Ela precisa estar acessível pela internet: sem proteção por senha e sem firewall bloqueando a Hubtel. O callback também funciona enquanto a loja está em modo de manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização (startup action) que deixa passar o callback, a URL do cron e o retorno do cliente vindo da Hubtel.

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

Verificações de pagamento em segundo plano (cron): a URL cron com um token secreto, criada quando a extensão é instalada. Chame-a a cada 5 minutos pelo cron do seu servidor, por exemplo com curl. Os pagamentos sem confirmação são então verificados novamente na Hubtel automaticamente: 20 minutos depois que o cliente foi enviado à Hubtel, mais uma vez após uma hora se o pagamento ainda estiver em aberto, e até 5 vezes com intervalos crescentes quando a Hubtel não pôde ser acessada. No OpenCart 4 a URL do cron tem a rota extension/wcp_hubtel_pay/payment/wcp_hubtel_pay.cron em vez de extension/payment/wcp_hubtel_pay/cron; copie-a exatamente como as configurações a mostram. Mantenha a URL em sigilo. A URL responde com uma linha curta, como OK checked=0.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a Hubtel confirma o pagamento. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order status after payment: o status definido depois que a Hubtel confirma o pagamento do valor exato do pedido em GHS. Padrão: Processando.

Hubtel payment on hold status: o status definido quando a Hubtel informa um valor pago diferente do total do pedido, ou quando o pedido não está em GHS. Uma observação no histórico do pedido explica isso. Padrão: Pendente, porque o OpenCart não tem o status On hold. Você pode criar um status próprio em System > Localisation > Order Statuses e selecioná-lo aqui.

Avançado

Debug log: registra as chamadas à API e os callbacks em hubtel_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para hubtel_p_debug.old.log.php. Chaves e dados de clientes não são registrados. Erros e avisos são sempre registrados, mesmo quando esta opção está desligada. Padrão: desligado.

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

Delete data on uninstall: quando ligado, desinstalar a extensão remove as configurações e o log dela. As tentativas de pagamento da Hubtel salvas para os pedidos sempre são mantidas. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. A API Key não é exportada.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. A API Key salva é mantida.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Mobile Money or card (Hubtel)). Na etapa Confirm Order, o cliente vê o ícone e a sua descrição. O OpenCart cria o pedido nesta etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria um checkout na Hubtel pelo total do pedido em GHS e envia o cliente para a página de pagamento da Hubtel. Lá o pagamento aparece como Order #, com o número do pedido e o nome da sua loja. Na página da Hubtel, o cliente paga com MTN MoMo, Telecel Cash, AirtelTigo Money, um cartão Visa ou Mastercard, ou GhQR. Cada clique em Confirm Order cria uma nova tentativa de pagamento, com referência própria, e as páginas antigas da Hubtel continuam pagáveis.

No OpenCart 4 o cliente escolhe o método de pagamento com o botão Choose do bloco de método de pagamento, na janela Payment method options, e clica em Confirm Order no final da página de finalização de compra.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago quando a Hubtel o confirma pela Transaction Status API: pelo callback, pela verificação feita quando o cliente retorna, 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, então o pagamento nunca é aplicado duas vezes. O pedido então recebe o status da forma padrão do OpenCart, com os e-mails habituais do pedido e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Se o pedido foi 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 a Hubtel ainda não tiver confirmado o pagamento quando o cliente voltar, uma página de Payment confirmation mostra 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. com os botões Check again e Back to checkout. O pedido recebe o status assim que a Hubtel confirma o pagamento. Se a 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, e o pedido permanece sem status.

Se o cliente clicar em Cancel na página da Hubtel, a extensão verifica primeiro 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 feito depois pela página da Hubtel cancelada ainda é aceito.

No OpenCart 4 as mensagens sobre um pagamento cancelado ou malsucedido aparecem acima da página de finalização de compra. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida; o OpenCart 4 atualiza o pedido da finalização de compra, então, depois de um cancelamento ou de um pagamento malsucedido, o cliente paga o mesmo pedido com uma nova tentativa de pagamento. Antes de uma nova tentativa, a extensão consulta a Hubtel sobre as tentativas não confirmadas deste pedido e de pedidos anteriores do mesmo carrinho (últimas 24 horas). Se alguma delas estiver paga, esse pagamento é aplicado e o cliente vai para a página de sucesso, em vez de pagar duas vezes. Uma alteração do carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de um pagamento próprio.

No OpenCart 4 o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio tempo (por exemplo, se você o cancelou), o cliente volta à finalização de compra com The Hubtel payment was not completed. You can try again or choose another payment method., e o próximo Confirm Order paga um novo pedido. Se o pedido já estiver pago e o carrinho agora tiver uma nova compra, Confirm Order recarrega a página de finalização de compra, e o próximo Confirm Order paga um novo pedido. Um pedido pago nunca é exibido como pago para um carrinho diferente.

Se a Hubtel não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, 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 erradas, Hubtel payments are not available at the moment. Please choose another payment method. Os detalhes vão para o log.

A extensão não oferece reembolsos pelo OpenCart, assinaturas, cartões salvos nem escolha do canal de pagamento dentro da loja.

Pedidos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado à Hubtel e não pagou, ou a Hubtel ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order status after payment (padrão Processando): o pagamento foi confirmado pelo valor exato do pedido em GHS. Uma observação mostra o valor, a transação da Hubtel, o método de pagamento e a referência.

Hubtel payment on hold status (padrão Pendente): a Hubtel informou um valor pago diferente do total do pedido, ou o pedido não está em GHS. O pedido não foi marcado como pago, e uma observação explica a divergência. Confira o pagamento no painel da Hubtel e atenda o pedido ou reembolse-o manualmente. Se depois for paga outra tentativa do mesmo pedido pelo valor correto, o pedido passa para Order status after payment.

Se outra tentativa de um pedido já pago também for paga, ou se outro pedido de um carrinho já pago for pago, o pedido já pago não é alterado. Uma observação pede que você reembolse o duplicado no seu painel da Hubtel. Um pagamento de um pedido que você tenha movido para outro status (por exemplo, cancelado) adiciona uma observação, e o pedido nunca é reaberto automaticamente. Quando a Hubtel informa que um pagamento foi reembolsado, é adicionada uma observação ao pedido.

As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox Hubtel Pay Gateway

Em Sales > Orders, abra um pedido pago com a Hubtel. Na parte de baixo da página do pedido, ao lado de History e Additional, a aba VibeFox Hubtel Pay Gateway lista as Hubtel payment attempts do pedido: data, referência e checkout da Hubtel, valor, status na Hubtel, transação e resultado. Abaixo das tentativas, lista as Hubtel notes do pedido, das mais recentes para as mais antigas. A aba é exibida aos usuários que têm acesso à extensão.

O botão Check Hubtel payment status verifica as tentativas mais recentes do pedido (até 5, das mais recentes para as mais antigas, parando assim que o pedido estiver pago), aplica o resultado e adiciona uma observação com o status de cada tentativa. O resultado aparece na aba. Você precisa do direito de modificar pedidos (Sales > Orders, definido em System > Users > User Groups). O botão também funciona para um pedido sem status. Um status definido por este botão é gravado diretamente, sem e-mails do pedido nem atualização do estoque; o callback, o retorno do cliente e o cron o definem da forma padrão.

Reembolsos

Reembolsos pelo OpenCart não são suportados. Reembolse o pagamento no painel da Hubtel e depois registre o reembolso no OpenCart. As devoluções de produtos em Sales > Returns não devolvem dinheiro pela Hubtel.

Chave de licença

A extensão 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 de Extensions > Extensions > Payments > VibeFox Hubtel Pay Gateway > Edit, acima das configurações. Cole 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: opencart-payment-hubtel e o link Manage licenses and domains in your account, que abre sua conta em vibefox.net. Apenas usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do painel administrativo (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 após liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças não puder ser acessado, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a Hubtel 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. Um usuário administrador conectado ao painel no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 esta prévia não está disponível: a loja não enxerga o login do administrador, por isso, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois de abrir a página Edit uma vez, um lembrete aparece no Dashboard do painel. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados, inclusive pelas verificações em segundo plano.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente quando você abre o Dashboard ou a página Edit do painel: uma vez por dia nos primeiros 14 dias após a chave ser inserida, depois uma vez por semana. Para a verificação da licença não é necessário nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A 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, a API Key e o número da conta de comerciante estão preenchidos e se a moeda do pedido é GHS. Verifique também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações. A página de configurações mostra um aviso quando as credenciais ou a moeda estão erradas.

O pagamento foi feito, mas o pedido continua sem status: o pagamento não pôde ser confirmado. Ative o Debug log e veja o campo Log na página da extensão. Um 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 foi incluído na lista de permitidos pela Hubtel. Verifique também se a URL de callback está acessível pela internet e se a URL cron está sendo chamada. Assim que a Hubtel responder, o próximo callback, a verificação em segundo plano, o retorno do cliente ou o Check Hubtel payment status definem o status do 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 requisição, ou o carrinho estava sendo confirmado por outra requisição no mesmo momento. O pagamento é verificado novamente 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ão faltando. Preencha-os; o pagamento será verificado novamente em segundo plano.

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

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

A URL cron responde Forbidden: o token na URL está errado. Copie a URL cron exatamente como as configurações a mostram. Após uma reinstalação com Delete data on uninstall ligado, o token é novo.

O pedido está no status de espera: leia as observações na aba VibeFox Hubtel Pay Gateway (veja Status do pedido), confira o pagamento no painel da Hubtel e atenda o pedido ou reembolse-o manualmente.

O cliente vê um erro depois de Confirm Order: ative o 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 pedido em outra moeda gera Hubtel accepts payments in Ghana cedis (GHS) only. Please choose another payment method. This payment method is not available. Please reload the checkout page. significa que a finalização de compra não corresponde mais ao pedido, ou que o método de pagamento foi desligado nesse meio tempo.

Para desenvolvedores: o evento do OpenCart wcp_hubtel_pay_icon altera o ícone do método de pagamento, e wcp_hubtel_pay_payment_description altera a descrição do pagamento na página da Hubtel.

Desinstalação

Vá até Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Hubtel Pay Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos valores padrão em uma reinstalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, também os seus eventos e a sua ação de inicialização, que deixa passar o callback, a URL do cron e o retorno do cliente no modo de manutenção). Se Delete data on uninstall estiver ligado, são removidas as demais configurações (título, descrição, credenciais de API, token do cron, chave do log de depuração) e o log. Se estiver desligado, elas são mantidas para uma reinstalação posterior. As tentativas de pagamento da Hubtel dos pedidos são sempre mantidas, então callbacks e verificações atrasados continuam funcionando após uma reinstalação. Os pedidos existentes mantêm suas observações de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, vá até Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Hubtel Pay Gateway na lista de extensões instaladas, depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

A Hubtel é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Hubtel.