VibeFox Pesapal for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.

Moeda: o carrinho 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 carrinho é cobrado na própria moeda; o módulo 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 na Pesapal: é preciso ter a chave e o segredo do consumidor de uma conta de comerciante na Pesapal. As chaves de teste e de produção são diferentes. As chaves de teste (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 de desenvolvedores). As chaves de produção vêm do painel de comerciante da Pesapal. Não há mais nada a configurar no painel da Pesapal: o módulo registra a própria URL de notificação. Sua loja precisa estar acessível pela internet, porque a Pesapal envia a ela as notificações de pagamento.

Chave de licença VibeFox: comprada 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 Pesapal 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 a chave e o segredo do consumidor de teste, ative Enable/Disable, clique em Save e faça um pedido de teste.

5. Informe a chave e o segredo do consumidor de produção, desative Sandbox mode e clique em Save para aceitar pagamentos reais.

Ao ser instalado, o módulo cria o status de pedido Pesapal payment on hold. O PrestaShop disponibiliza o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitar isso em Payment > Preferences.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Pesapal Pay Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, um selo mostra o modo: SANDBOX — Test payments on cybqa.pesapal.com — no real money is charged. ou LIVE — Real payments on pay.pesapal.com. Um aviso aparece quando faltam as chaves do modo atual (Enter the sandbox consumer key and secret — until then Pesapal is not shown at checkout., ou o mesmo texto para o modo live) e quando a Pesapal não oferece suporte à moeda padrão da sua loja.

Pesapal

Enable/Disable: Enable Pesapal 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: Pesapal (M-Pesa, Airtel Money, cards). Obrigatório: um título vazio não é salvo e o anterior é mantido.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with M-Pesa, Airtel Money, card or bank via Pesapal. You will be redirected to Pesapal to complete the payment.

Credenciais da API

Esta seção explica onde obter as chaves e tem links para cybqa.pesapal.com e pesapal.com. Informe as chaves de teste e 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 teste. Desative para aceitar pagamentos reais em pay.pesapal.com com as chaves de produção. Padrão: ativado.

Sandbox consumer key: a chave do consumidor da sua conta de comerciante de teste (demonstração). Usada apenas no modo sandbox.

Sandbox consumer secret: o segredo do consumidor da sua conta de comerciante de teste. Usado apenas no modo sandbox.

Live consumer key: a chave do consumidor do seu painel de comerciante na Pesapal. Usada quando o modo sandbox está desativado.

Live consumer secret: o segredo do consumidor do seu painel de comerciante na Pesapal. Usado quando o modo sandbox está desativado.

Chaves e segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo.

Clear saved consumer keys and secrets: marque a caixa e clique em Save para remover as quatro chaves e segredos salvos.

Salvar as configurações descarta os tokens de acesso da Pesapal em cache. Trocar de modo ou de chaves nunca reutiliza 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 modo, mesmo depois de você trocar.

Notificações de pagamento (IPN)

IPN URL: mostra a URL de notificação da sua loja. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_pesapal_pay/webhook, possivelmente com um código de idioma como /en/. A URL é registrada automaticamente na Pesapal no primeiro pagamento, separadamente para teste e produção e para cada par de chaves, então não há nada a configurar. Depois do primeiro pagamento, a seção mostra Registered IPN ID: com o ID retornado pela Pesapal; antes disso, mostra Not registered yet for the current mode and keys. A URL precisa estar acessível pela internet: sem firewall nem proteção por senha à frente. Ela continua funcionando enquanto a loja está em manutenção e não é bloqueada pela restrição de países da sua loja.

Avançado

Debug log: Log Pesapal requests and notifications. Grava os detalhes em logs/pesapal_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, mesmo com a opção desativada. Chaves, tokens e dados de clientes nunca são registrados. Padrão: desativado.

Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.

Delete data: Delete the module settings and logs when the module is uninstalled. Os dados da Pesapal salvos nos pedidos (IDs de rastreamento, notas) fazem parte do histórico de pagamentos e são sempre mantidos. Desativar o módulo não apaga nada. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Pesapal (M-Pesa, Airtel Money, cards)) e vê sua descrição. Após a confirmação, o módulo cria uma solicitação de pagamento na Pesapal pelo total do carrinho, na moeda do carrinho, com os dados de cobrança do endereço de fatura, e envia o cliente para a página de pagamento da Pesapal. A descrição do pagamento enviada à Pesapal é Cart, o número do carrinho e o nome da loja. Ali o cliente paga com um dos métodos oferecidos pela Pesapal, como M-Pesa, Airtel Money, MTN, cartão ou transferência bancária. Neste ponto, ainda não existe nenhum pedido.

O pedido só é marcado como pago depois que a Pesapal o confirma. As notificações da Pesapal e o retorno do cliente não contêm dados de pagamento nem assinatura, então o módulo não confia neles: para cada um, consulta o status da transação na Pesapal por meio de uma requisição autenticada entre servidores, no modo em que o pagamento foi iniciado. Também verifica se a transação pertence a este carrinho e se o valor e a moeda pagos correspondem ao carrinho. Então o pedido é criado e o cliente vê a página padrão de confirmação de pedido.

Pagamentos por dinheiro móvel podem levar alguns instantes. Se a Pesapal ainda não tiver confirmado o pagamento quando o cliente voltar, uma página de Payment confirmation mostra Your payment is being confirmed by Pesapal. 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. A notificação da Pesapal cria o pedido assim que o pagamento é confirmado. Se o pedido tiver sido colocado em espera, a página de confirmação mostra Your payment was received and is being reviewed by the shop. You will receive an e-mail once the order is confirmed.

Se o cliente cancelar na página da Pesapal, ele volta à finalização de compra com a mensagem The Pesapal payment was cancelled. You can try again or choose another payment method. Se o pagamento falhar, a mensagem é The Pesapal payment was not successful. Please try again or choose another payment method. O carrinho é mantido e o cliente pode pagar novamente. Cada tentativa de pagamento do carrinho é lembrada, então um pagamento feito depois em uma página anterior da Pesapal do carrinho também é aceito.

Se a Pesapal não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo Pesapal is temporarily unavailable. Please try again in a few minutes or choose another payment method., Pesapal is not available at the moment. Please choose another payment method. (chaves incorretas) ou Pesapal could not start the payment: seguido do motivo informado pela Pesapal. O motivo técnico é gravado no registro. O total do pedido precisa ser maior que zero.

O módulo 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, assinaturas ou pagamentos recorrentes, e não faz conversão de moeda.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado à Pesapal e não pagou, o pagamento falhou ou a Pesapal ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: a Pesapal informa o pagamento como concluído, e o valor e a moeda correspondem. O pagamento é registrado com o ID de rastreamento da Pesapal como ID da transação, e 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: o valor ou a moeda pagos diferem do carrinho (nota Pesapal amount/currency mismatch — held for review), ou chegou dinheiro para um pedido que havia sido cancelado. O valor efetivamente pago é registrado no pedido quando está na moeda do pedido. Verifique o pagamento no painel da Pesapal e depois conclua o pedido ou reembolse o pagamento.

Refunded: a Pesapal informa que o pagamento que quitou o pedido foi estornado. O estorno de outra tentativa é apenas anotado no pedido.

Se uma segunda tentativa de pagamento de um carrinho já pago também for concluída, o pedido não muda. Uma nota pede que você reembolse o segundo pagamento no painel da Pesapal. Pedidos cancelados e reembolsados nunca são reabertos automaticamente.

Bloco de pagamento Pesapal

A página do pedido mostra um bloco Pesapal payment com um selo Sandbox ou Live, o ID de rastreamento, 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 revisão, todas as Payment attempts do carrinho e as Payment notes do pedido. O bloco é somente leitura.

Reembolsos

O módulo não envia reembolsos à Pesapal. Reembolse o pagamento no painel da Pesapal e depois registre o reembolso manualmente no PrestaShop.

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 Pesapal Pay Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Pesapal 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-pesapal e o link Manage licenses and domains in your account, que abre a sua conta em 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 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 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ê This payment method is not available. Please choose another one. A vitrine do 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 pode 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, e as notificações da Pesapal sobre pagamentos existentes, incluindo estornos, continuam sendo aplicadas.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem a 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. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo 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á ativado, se a chave e o segredo do consumidor 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 live) e se a moeda do carrinho é KES, UGX, TZS, ZMW, RWF ou USD. Os avisos no topo das configurações indicam o problema. 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. Desenvolvedores podem alterar a lista de moedas com o hook actionPesapalSupportedCurrencies.

O pagamento foi feito, mas nenhum pedido foi criado: a notificação da Pesapal não chegou à sua loja e o cliente não voltou. Verifique se a URL exibida em IPN URL está acessível pela internet (sem firewall nem proteção por senha à frente). Ative o Debug log e consulte o campo Log na página do módulo.

Como a loja responde às notificações: uma notificação processada recebe HTTP 200. Quando o módulo não consegue processá-la, responde com erro, e a Pesapal envia a notificação novamente depois: 400 (ID de rastreamento ausente ou malformado), 404 (nenhum carrinho desta loja tem esse ID de rastreamento), 409 (a transação pertence a outra referência de comerciante; nada é alterado), 502 (a API da Pesapal não pôde ser acessada naquele momento, ou faltam as chaves do modo em que o pagamento foi iniciado) e 503 (o carrinho estava sendo atualizado pelo retorno do cliente no mesmo instante, ou o pedido não pôde ser criado, por exemplo porque o módulo está desativado).

O cliente vê Pesapal is not available at the moment: a Pesapal rejeitou a chave ou o segredo do consumidor do modo atual. Verifique se as chaves pertencem ao modo: chaves de teste funcionam apenas no sandbox, e chaves de produção apenas no modo live. O registro mostra o erro da Pesapal.

O cliente vê Pesapal is temporarily unavailable: a Pesapal não pôde ser acessada, ou a URL de notificação não pôde ser registrada. Leia o registro e tente novamente.

Pagamentos de um modo anterior não são confirmados após a 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.

Pedido em Pesapal payment on hold após o pagamento: leia as notas no bloco Pesapal payment. O valor ou a moeda pagos diferiam do carrinho, 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.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Pesapal Pay Gateway e escolha Uninstall. A chave de licença e o status de licença deste módulo são sempre removidos. Os tokens de acesso da Pesapal em cache e os IDs de notificação registrados são sempre removidos. Se Delete data estiver ativado, as configurações do módulo e o registro também são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As tentativas de pagamento da Pesapal e o status de pedido Pesapal payment on hold são sempre mantidos. Os pedidos existentes conservam suas notas de pagamento, IDs de transação e IDs de rastreamento da Pesapal.

A Pesapal é uma marca de seu respectivo titular. Este módulo não é afiliado nem endossado pela Pesapal.