VibeFox Pesapal for OpenCart — Ajuda
Requisitos
OpenCart: 3.0.x (testado na versão 3.0.5.0) ou 4.0.2 e posteriores (testado na versão 4.1.0.3).
PHP: 8.0 ou superior.
Moeda: o pedido precisa estar em KES, UGX, TZS, ZMW, RWF ou USD. Em outras moedas, o método de pagamento fica oculto na finalização de compra. O pedido é cobrado na própria moeda; a extensão não converte moedas. Os valores são enviados em unidades principais, arredondados conforme a precisão da moeda (UGX e RWF sem casas decimais).
Conta Pesapal: você precisa da consumer key e do consumer secret de uma conta de comerciante Pesapal. As chaves de sandbox e as de produção são diferentes. As chaves de sandbox vêm de uma conta de comerciante de demonstração em cybqa.pesapal.com (a Pesapal também publica chaves de demonstração no portal para desenvolvedores). As chaves de produção vêm do painel do comerciante na Pesapal. Não é preciso configurar mais nada no painel da Pesapal: a extensão registra sozinha a URL de notificação. A sua loja precisa estar acessível pela internet, porque a Pesapal envia para ela as notificações de pagamento.
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 para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém README.txt, o pacote do OpenCart 3 wcp_pesapal_pay-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_pesapal_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á em Extensions > Installer, clique em Upload e escolha o arquivo wcp_pesapal_pay-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.
2. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Pesapal Pay Gateway e clique em Install (o botão verde +). O seu usuário administrador precisa ter permissão para alterar 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 a 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 a consumer key e o consumer secret de sandbox, ative Enable/Disable, clique em Save e faça um pedido de teste.
5. Informe a consumer key e o consumer secret de produção, desative Sandbox mode e clique em Save para aceitar pagamentos reais.
OpenCart 4
1. No painel administrativo, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_pesapal_pay.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir 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á em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Pesapal 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 e as chaves da Pesapal como nos passos 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a IPN URL é diferente (veja Notificações de pagamento).
Uma instalação nova começa com o método de pagamento desativado e o modo sandbox ativado.
Configuração
Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Pesapal Pay Gateway > Edit. As seções ficam listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, um selo mostra o modo: SANDBOX — Pagamentos de teste em cybqa.pesapal.com — nenhum dinheiro real é cobrado. ou LIVE — Pagamentos reais em pay.pesapal.com. Um aviso aparece quando faltam as chaves do modo atual (Informe a consumer key e o secret de sandbox — até lá, a Pesapal não é exibida na finalização de compra., ou a mesma mensagem para o modo de produção) e quando a Pesapal não oferece suporte à moeda padrão da sua loja. Sem a permissão para alterar a extensão, a página mostra as configurações, mas não consegue salvá-las.
Ao salvar, um Title vazio não é aceito: o título anterior é mantido com um erro, e os demais campos são salvos. Sort Order precisa ser um número inteiro (valores negativos são permitidos), Total um número igual ou maior que 0, e Geo Zone e os status de pedido precisam existir; caso contrário, esse campo mantém o valor anterior com um erro. Ao salvar, os tokens de acesso da Pesapal em cache são descartados.
Pesapal
Enable/Disable: Enable Pesapal 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: Pesapal (M-Pesa, Airtel Money, cards). Obrigatório, no máximo 128 caracteres.
Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.
Sort Order: a posição da Pesapal entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.
Geo Zone: oferece a Pesapal apenas para endereços de pagamento da zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.
Total: o valor total do carrinho, na moeda padrão da loja, que um pedido precisa atingir para que a Pesapal seja oferecida. Deixe em branco para oferecer a Pesapal em qualquer valor.
Credenciais de API
Esta seção explica onde obter as chaves e tem links para cybqa.pesapal.com e pesapal.com. Informe as chaves de sandbox e as de produção, cada uma no seu campo.
Sandbox mode: Use the Pesapal sandbox (no real money). Quando ativado, os novos pagamentos usam cybqa.pesapal.com com as chaves de sandbox. Desative para aceitar pagamentos reais em pay.pesapal.com com as chaves de produção. Padrão: ativado.
Sandbox consumer key: a consumer key da sua conta de comerciante de sandbox (demonstração). Usada somente no modo sandbox.
Sandbox consumer secret: o consumer secret da sua conta de comerciante de sandbox. Usado somente no modo sandbox.
Live consumer key: a consumer key do painel do comerciante na Pesapal. Usada quando o modo sandbox está desativado.
Live consumer secret: o consumer secret do painel do comerciante na Pesapal. Usado quando o modo sandbox está desativado.
Chaves e secrets salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo — deixe em branco para mantê-lo. Informe um valor novo somente se quiser alterá-lo.
Clear saved consumer keys and secrets: aparece quando uma chave está salva. Marque a caixa e clique em Save para remover as quatro chaves e secrets salvos.
Trocar de modo ou alterar chaves nunca reaproveita um token de acesso ou um ID de notificação do outro modo ou de outras chaves. Um pagamento iniciado em um modo é sempre verificado nesse mesmo modo, mesmo depois da troca.
Status de pedido
O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a Pesapal informa o pagamento como «Completed». Cada campo abaixo lista os seus status de pedido do OpenCart.
Order Status After Payment: o status definido quando a Pesapal confirma o pagamento. Padrão: Processing.
Pesapal Payment On Hold Status: pagamentos cujo valor ou moeda não correspondem ao pedido, e pagamentos recebidos depois de um cancelamento. Uma nota explica o motivo. Padrão: Pending, pois o OpenCart não tem um status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.
Cancelled Order Status: um pagamento da Pesapal que chega para um pedido neste status (ou no status de reembolsado) coloca o pedido em espera, em vez de reabri-lo silenciosamente. Padrão: Canceled.
Refunded Status: definido quando a Pesapal informa que o pagamento do pedido foi revertido. Padrão: Refunded.
Notificações de pagamento (IPN)
IPN URL: mostra a URL de notificação da sua loja. No OpenCart 3 ela tem a forma https://your-store/index.php?route=extension/payment/wcp_pesapal_pay/ipn, e no OpenCart 4, https://your-store/index.php?route=extension/wcp_pesapal_pay/payment/wcp_pesapal_pay.ipn. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. A URL é registrada automaticamente na Pesapal no primeiro pagamento, separadamente para sandbox e produção e para cada consumer key, então não há nada para configurar. Depois do primeiro pagamento, a seção mostra Registered IPN ID: com o ID retornado pela Pesapal; antes disso, mostra Ainda não registrado para o modo e as chaves atuais. A URL precisa ser acessível pela internet: sem firewall ou proteção por senha na frente dela. Ela continua funcionando enquanto a loja está em modo de manutenção, porque o OpenCart deixa passar as requisições das extensões de pagamento (no OpenCart 4, a extensão adiciona para isso uma ação de inicialização própria, que também deixa passar o retorno do cliente da Pesapal).
Avançado
Debug log: registra as requisições e notificações da Pesapal em pesapal_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao chegar a 5 MB, é movido para pesapal_p_debug.old.log.php. Erros e avisos são sempre registrados, mesmo com a chave desligada. Chaves, tokens e dados de clientes nunca são registrados. Padrão: desligado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data: apaga as configurações da extensão e os logs quando ela é desinstalada. Os dados da Pesapal salvos nos pedidos (IDs de rastreamento, notas) fazem parte do histórico de pagamentos e são sempre mantidos. Desativar a extensão não apaga nada. Padrão: desligado.
Importar / Exportar
Export: Download JSON salva as configurações em um arquivo JSON. As consumer keys e os secrets não são exportados.
Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As consumer keys e os secrets salvos são mantidos.
Finalização de compra
Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Pesapal (M-Pesa, Airtel Money, cards)). Na etapa Confirm Order, o cliente vê a sua descrição. O OpenCart cria o pedido nessa etapa, ainda sem status. No OpenCart 4, o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order no final da página de finalização de compra. Quando o cliente clica em Confirm Order, a extensão cria uma solicitação de pagamento na Pesapal pelo total do pedido na moeda do pedido, com os dados de cobrança do endereço de pagamento (no OpenCart 4, quando a finalização de compra não pede endereço de pagamento, o de entrega), e envia o cliente para a página de pagamento da Pesapal. A descrição do pagamento enviada à Pesapal é Order, o número do pedido e o nome da loja. Lá o cliente paga com um dos métodos oferecidos pela Pesapal, como M-Pesa, Airtel Money, MTN, cartão ou banco. Uma nota no pedido registra a solicitação de pagamento.
O pedido só é marcado como pago depois que a Pesapal confirma. As notificações da Pesapal e o retorno do cliente não trazem dados de pagamento nem assinatura, então a extensão não confia neles: para cada um, ela consulta a Pesapal sobre o status da transação com uma requisição autenticada de servidor para servidor, no modo em que o pagamento foi iniciado. Ela também confere se a transação pertence a este pedido e se o valor e a moeda pagos correspondem ao pedido. Em seguida, o pedido 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.
Pagamentos por mobile money podem levar um momento. Se a Pesapal ainda não tiver confirmado o pagamento quando o cliente voltar, uma página Payment confirmation mostra Seu pagamento está sendo confirmado pela Pesapal. Você receberá um e-mail assim que ele for confirmado — não é preciso pagar novamente. com os botões Check again e Back to checkout. A notificação da Pesapal define o status do pedido assim que o pagamento é confirmado. Se o pedido tiver sido colocado em espera, a página de sucesso mostra Seu pagamento foi recebido e está sendo analisado pela loja. Você receberá um e-mail assim que o pedido for confirmado. Quando um pagamento posterior passa o pedido do status de espera para o status de pago, o cliente é avisado por e-mail.
Se o cliente cancelar na página da Pesapal, ele volta à finalização de compra com a mensagem O pagamento pela Pesapal foi cancelado. Você pode tentar novamente ou escolher outro método de pagamento. Se o pagamento falhar, a mensagem é O pagamento pela Pesapal não foi concluído. Tente novamente ou escolha outro método de pagamento., e uma nota no pedido informa o motivo. O carrinho é mantido e o cliente pode pagar de novo. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra. O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, e o OpenCart 4 atualiza o pedido da finalização de compra; por isso, antes de um novo pagamento, a extensão verifica na Pesapal as tentativas anteriores do carrinho: se uma delas tiver sido paga nesse meio-tempo, esse pedido recebe o status e o cliente vai para a página de sucesso sem pagar duas vezes. Um pagamento feito depois em uma página antiga da Pesapal do carrinho continua sendo aceito. Uma alteração no carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa do próprio pagamento.
O OpenCart 4 mantém o pedido na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado nesse meio-tempo (por exemplo, você o cancelou), ou se tiver sido pago por um carrinho anterior que mudou desde então, o cliente volta à finalização de compra com a mensagem Seu pedido anterior já está fechado. Confirme o pedido novamente: o carrinho será pago com um novo pedido. O próximo clique em Confirm Order paga um novo pedido. Um pedido fechado nunca é exibido como pago.
Se a Pesapal não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão, por exemplo A Pesapal está temporariamente indisponível. Tente novamente em alguns minutos ou escolha outro método de pagamento., A Pesapal não está disponível no momento. Escolha outro método de pagamento. (chaves incorretas) ou A Pesapal não conseguiu iniciar o pagamento: seguido do motivo informado pela Pesapal. O motivo técnico é gravado no log e nas notas do pedido. O total do pedido precisa ser maior que zero.
A extensão não tem formulário de pagamento no seu próprio site (o cliente sempre paga na página da Pesapal), não tem cartões salvos, nem assinaturas ou pagamentos recorrentes, nem conversão de moeda.
Pedidos e reembolsos
Status de pedido
Sem status (pedido ausente): o cliente foi enviado à Pesapal e não pagou, o pagamento falhou ou a Pesapal ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders.
Order Status After Payment (padrão Processing): a Pesapal informa o pagamento como Completed e o valor e a moeda correspondem. Uma nota mostra o valor, o método de pagamento, o código de confirmação da Pesapal e o ID de rastreamento. Cada pagamento é aplicado uma única vez.
Pesapal Payment On Hold Status (padrão Pending): o valor ou a moeda pagos diferem do pedido (nota Pesapal amount/currency mismatch — held for review), ou chegou dinheiro para um pedido no status cancelado ou reembolsado. Verifique o pagamento no painel da Pesapal e, depois, conclua o pedido ou reembolse o pagamento.
Refunded Status (padrão Refunded): a Pesapal informa que o pagamento que quitou o pedido foi revertido. A reversão de outra tentativa fica apenas registrada no pedido.
Se um segundo pagamento de um pedido ou carrinho já pago também for concluído, o pedido não é alterado. Uma nota no pedido pago pede que você reembolse o segundo pagamento no painel da Pesapal. Pedidos cancelados e reembolsados nunca são reabertos automaticamente.
As notas são entradas do History do pedido que o cliente não vê.
VibeFox Pesapal Pay Gateway tab
Em Sales > Orders, abra um pedido pago com a Pesapal. No final da página do pedido, ao lado de History e Additional, a aba VibeFox Pesapal Pay Gateway mostra o ID de rastreamento com o selo Sandbox ou Live, a referência do comerciante, o status na Pesapal, o método de pagamento, o código de confirmação, o valor solicitado e o valor pago, o motivo de uma análise, todas as Payment attempts do pedido (quando há mais de uma) e as Payment notes. A aba é somente leitura e é exibida aos usuários que têm acesso à extensão.
Reembolsos
A extensão não envia reembolsos à Pesapal. Reembolse o pagamento no painel da Pesapal e, depois, registre o reembolso manualmente no OpenCart. As devoluções de produtos em Sales > Returns não devolvem dinheiro pela Pesapal.
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 Pesapal Pay Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Pesapal 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo, aparecem a linha Product: opencart-payment-pesapal e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify sobre 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 de mudar o endereço da loja, ou depois de 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 único domínio: o endereço da loja definido na configuração 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 Pesapal 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. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (sem licença — visível somente para administradores), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login no painel administrativo, então 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 administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e as notificações da Pesapal sobre pagamentos existentes, inclusive reversões, continuam sendo aplicadas.
Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem a renovação. O status é verificado novamente de forma automática ao abrir o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias depois de informar a chave e, depois, uma vez por semana. Não é necessário cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.
Solução de problemas
A Pesapal não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se a consumer key e o secret do modo atual estão informados (Sandbox consumer key e Sandbox consumer secret no modo sandbox, Live consumer key e Live consumer secret no modo de produção) e se a moeda do pedido é KES, UGX, TZS, ZMW, RWF ou USD. Os avisos no topo das configurações indicam o problema. Confira também se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.
O pagamento foi feito, mas o pedido continua sem status: a notificação da Pesapal não chegou à sua loja e o cliente não voltou. Verifique se a URL exibida em IPN URL é acessível pela internet (sem firewall ou proteção por senha na frente dela). Ative o Debug log e veja o campo Log na página da extensão.
Como a loja responde às notificações: uma notificação processada recebe a resposta HTTP 200. Quando a extensão não consegue processá-la, ela responde com um erro, e a Pesapal envia a notificação novamente mais tarde: 400 (ID de rastreamento ausente ou malformado), 404 (nenhum pedido desta loja tem este ID de rastreamento), 409 (a transação pertence a outra referência de comerciante; nada é alterado), 502 (não foi possível acessar a API da Pesapal naquele momento, ou faltam as chaves do modo em que o pagamento foi iniciado) e 503 (o pedido estava sendo processado no mesmo momento pelo retorno do cliente, ou não foi possível definir o status do pedido).
O cliente vê a mensagem «Pesapal is not available at the moment»: a Pesapal rejeitou a consumer key ou o secret do modo atual. Confira se as chaves correspondem ao modo: chaves de sandbox funcionam só no sandbox, e chaves de produção só no modo de produção. O log mostra o erro da Pesapal.
O cliente vê a mensagem «Pesapal is temporarily unavailable»: não foi possível acessar a Pesapal, ou a URL de notificação não pôde ser registrada. Leia o log e tente novamente.
O cliente vê a mensagem «This payment method is not available. Please reload the checkout page.»: a sessão da finalização de compra não corresponde mais ao pedido, ou o método de pagamento foi desligado nesse meio-tempo. O cliente recarrega a finalização de compra.
O cliente vê a mensagem «We could not verify the Pesapal payment»: o link de retorno da Pesapal não correspondeu a nenhum pedido da loja. Se houve cobrança, localize o pagamento no painel da Pesapal e confira o pedido antes que o cliente pague novamente.
Pagamentos de um modo anterior não são confirmados depois da troca: um pagamento é verificado com as chaves do modo em que foi iniciado. Mantenha as chaves desse modo informadas até que os pagamentos dele sejam confirmados.
O pedido está no status de espera após o pagamento: leia as notas na aba VibeFox Pesapal Pay Gateway. O valor ou a moeda pagos diferiam do pedido, ou o pagamento chegou depois que o pedido foi cancelado. Verifique o pagamento no painel da Pesapal e, depois, processe o pedido ou reembolse o pagamento.
Para desenvolvedores: a extensão dispara os eventos do OpenCart pesapal_p_supported_currencies (a lista de moedas) e pesapal_p_submit_order_payload (a solicitação de pagamento antes de ser enviada à Pesapal).
Desinstalação
Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Pesapal 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 Status de pedido, que voltam aos padrões em uma reinstalação. O evento do OpenCart da extensão, os tokens de acesso da Pesapal em cache e os IDs de notificação registrados também são sempre removidos (no OpenCart 4, também os eventos e a ação de inicialização da extensão, que deixam passar as notificações e o retorno do cliente no modo de manutenção). Se Delete data estiver ligado, as demais configurações (título, descrição, modo sandbox, chaves, chave do debug log) e o log são removidos. Se estiver desligado, elas são mantidas para uma reinstalação posterior. As tentativas de pagamento da Pesapal são sempre mantidas. Os pedidos existentes mantêm as notas de pagamento e os IDs de rastreamento da Pesapal.
No OpenCart 4, para remover também os arquivos da extensão, vá em Extensions > Installer depois da desinstalação e clique em Uninstall (o botão laranja −) ao lado de VibeFox Pesapal Pay Gateway na lista de extensões instaladas e, em seguida, em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.
A Pesapal é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Pesapal.