VibeFox Pesapal for WooCommerce — Ajuda

Requisitos

WordPress: 6.2 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não permite a ativação sem ele.

PHP: 8.0 ou superior.

Currency: o pedido deve 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; o plugin não converte moedas. Os valores são enviados em unidades principais, arredondados para a precisão da moeda (UGX e RWF sem casas decimais).

Pesapal account: você precisa da chave e do segredo do consumidor de uma conta de comerciante na Pesapal. As chaves de teste e produção são diferentes. As chaves de teste 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 seu painel de comerciante da Pesapal. Não é preciso configurar mais nada no painel da Pesapal: o plugin registra a própria URL de notificação. Seu site deve ser acessível pela internet, pois a Pesapal envia notificações de pagamento para ele.

VibeFox license key: comprada em vibefox.net. Uma chave funciona em um domínio.

Instalação

1. No WordPress, acesse Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_pesapal_pay para /wp-content/plugins/ por FTP.

2. Clique em Activate.

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

4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Digite a chave e o segredo do consumidor de teste, ative Enable/Disable, salve e faça um pedido de teste.

6. Digite a chave e o segredo do consumidor de produção, desmarque Sandbox mode e salve para aceitar pagamentos reais.

Configuração

Todas as configurações ficam em uma página: WooCommerce > Settings > Payments > Pesapal. Acima dos campos, um indicador mostra o modo: SANDBOX com Test payments on cybqa.pesapal.com — no real money is charged. ou LIVE com 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 equivalente para produção) e quando a Pesapal não aceita a moeda da loja. Na lista de métodos de pagamento, a Pesapal é marcada como modo de teste enquanto o ambiente de teste estiver ativado.

Notificações de pagamento (IPN)

Este bloco mostra a URL de notificação da loja. Ela tem o formato https://your-site/wc-api/pesapal_pay/. A URL é registrada automaticamente na Pesapal no primeiro pagamento, separadamente para teste e produção e para cada par de chaves, portanto não há nada a configurar. Após o primeiro pagamento, o bloco mostra Registered IPN ID: com o ID retornado pela Pesapal; antes disso, informa Not registered yet for the current mode and keys. A URL deve ser acessível pela internet: sem modo de manutenção, firewall ou proteção por senha bloqueando o acesso.

Finalização de compra

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

Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: Pesapal (M-Pesa, Airtel Money, cards).

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

A seção explica onde obter as chaves e contém links para cybqa.pesapal.com e pesapal.com. Digite as chaves de teste e produção em seus respectivos campos. Todos os campos de chaves são campos de senha.

Sandbox mode: Use the Pesapal sandbox (no real money). Quando ativado, os novos pagamentos usam cybqa.pesapal.com com as chaves de teste. Desmarque 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 de teste.

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

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

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

Trocar o modo ou alterar as chaves nunca reutiliza um token de acesso ou ID de notificação de outro modo ou de outras chaves. Um pagamento iniciado em um modo é sempre verificado nesse modo, mesmo após a troca.

Avançado

Debug log: Log Pesapal requests and notifications grava detalhes em WooCommerce > Status > Logs, origem wcp_pesapal_pay. Erros e avisos são sempre registrados. Chaves, tokens e dados de clientes nunca são registrados. Padrão: desativado.

Delete data: Delete the plugin settings and logs when the plugin is deleted. Os dados da Pesapal salvos nos pedidos (IDs de rastreamento, notas) são o histórico de pagamentos e sempre são mantidos. Desativar o plugin nunca exclui nada. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Pesapal (M-Pesa, Airtel Money, cards)) e faz o pedido. No modo de teste, o bloco de Finalização de compra mostra Sandbox mode: no real money will be charged. O plugin cria uma solicitação de pagamento na Pesapal pelo total do pedido na moeda do pedido, com os dados de faturamento do pedido, e adiciona uma nota com o modo, o valor e o ID de rastreamento da Pesapal. O cliente é direcionado à página de pagamento da Pesapal e paga com um dos métodos oferecidos, como M-Pesa, Airtel Money, MTN, cartão ou banco.

O pedido só é marcado como pago após a confirmação da Pesapal. As notificações da Pesapal e o retorno do cliente não contêm dados de pagamento nem assinatura, por isso o plugin não confia neles: para cada um, consulta o status da transação na Pesapal com uma solicitação autenticada entre servidores, no modo em que o pagamento foi iniciado. Também verifica se a transação pertence a este pedido e se o valor pago e a moeda correspondem ao pedido.

Após pagar, o cliente volta à página de pedido recebido. Pagamentos com dinheiro móvel podem levar alguns instantes. Se o pagamento ainda não estiver confirmado, a página 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. A notificação da Pesapal conclui o pedido depois. Se o pedido foi colocado em espera, a página 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, volta à página Pay for order com The Pesapal payment was cancelled. You can try again or choose another payment method. Se o pagamento falhar, a mensagem será The Pesapal payment was not successful. Please try again or choose another payment method. O cliente pode pagar o mesmo pedido novamente. Cada tentativa de pagamento do pedido é lembrada, portanto um pagamento feito mais tarde em uma página anterior da Pesapal do pedido também é aceito.

Se a Pesapal não puder iniciar o pagamento, o cliente verá 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: seguida do motivo informado pela Pesapal. Os detalhes técnicos vão para as notas do pedido e o log. O total do pedido deve ser maior que zero.

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. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).

O plugin não tem formulário de pagamento na própria página de finalização de compra (o cliente sempre paga na página da Pesapal), cartões salvos, assinaturas ou pagamentos recorrentes nem conversão de moedas.

Pedidos e reembolsos

Status dos pedidos

Pending payment: o cliente foi direcionado à Pesapal e ainda não pagou, ou a Pesapal ainda não confirmou o pagamento.

Processing: a Pesapal informa que o pagamento foi concluído e o valor e a moeda correspondem. A nota do pedido mostra o valor, o método de pagamento, o código de confirmação da Pesapal e o ID de rastreamento. O ID da transação do pedido é o ID de rastreamento da Pesapal. Cada pagamento é aplicado uma vez.

On hold: o valor pago ou a moeda difere do pedido (nota Pesapal amount/currency mismatch — held for review), ou chegou dinheiro para um pedido que havia sido cancelado antes do pagamento. Confira o pagamento no painel da Pesapal e depois conclua o pedido ou reembolse o pagamento.

Failed: a Pesapal informa que a última tentativa de pagamento falhou. A nota informa o motivo fornecido pela Pesapal. Se o cliente tentar novamente pela página Pay for order e essa tentativa também falhar, outra nota com o motivo será adicionada. A falha de uma tentativa anterior não altera o pedido. O cliente pode pagar novamente.

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

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

Reembolsos

O plugin não envia reembolsos à Pesapal. Reembolse o pagamento no painel da Pesapal e depois registre o reembolso manualmente 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 no topo de WooCommerce > Settings > Payments > Pesapal. 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 está ativa e 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 sua conta vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta 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 verá This payment method is not available. Please choose another one. Os gerentes de loja conectados continuam vendo o método de pagamento, marcado com (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página de plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados pela notificação da Pesapal e pelo retorno do cliente.

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

Solução de problemas

A Pesapal não aparece na finalização de compra: verifique se a licença está ativa, Enable/Disable está ativado, a chave e o segredo do consumidor do modo atual foram informados (Sandbox consumer key e Sandbox consumer secret no modo de teste, Live consumer key e Live consumer secret em produção) e a moeda do pedido é KES, UGX, TZS, ZMW, RWF ou USD. Os avisos no topo das configurações indicam o problema. Desenvolvedores podem alterar a lista de moedas com o filtro pesapal_p_supported_currencies.

O pagamento foi realizado, mas o pedido continua Aguardando pagamento: a notificação da Pesapal não chegou à loja e o cliente não retornou. Verifique se a URL exibida em Payment notifications (IPN) é acessível pela internet (sem modo de manutenção, firewall ou proteção por senha bloqueando /wc-api/pesapal_pay/). Consulte WooCommerce > Status > Logs, origem wcp_pesapal_pay.

Como a loja responde às notificações: uma notificação processada recebe uma resposta HTTP 200. Quando o plugin não consegue processá-la, responde com um erro e a Pesapal envia a notificação novamente depois: 400 (ID de rastreamento ausente ou malformado), 404 (nenhum pedido desta loja tem esse ID de rastreamento), 409 (a transação pertence a outra referência de comerciante; o pedido não é alterado), 502 (a API da Pesapal não pôde ser acessada naquele momento) e 503 (o pedido estava sendo atualizado pelo retorno do cliente ao mesmo tempo).

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 ambiente de teste, chaves de produção apenas em produção. A nota do pedido mostra o erro da Pesapal.

O cliente vê Pesapal is temporarily unavailable: não foi possível acessar a Pesapal ou registrar a URL de notificação. Leia a nota do pedido e o log e tente novamente.

O pedido fica Em espera após o pagamento: leia a nota do pedido. O valor pago ou a moeda diferia do pedido, ou o pagamento chegou após o cancelamento do pedido. Confira o pagamento no painel da Pesapal e depois processe o pedido ou reembolse o pagamento.

O bloco de licença mostra um erro: siga a mensagem no bloco. Por exemplo, se a chave já está em uso em outro domínio, libere uma vaga na sua conta 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 acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua o plugin na página Plugins. A chave e o status da licença deste plugin, os tokens de acesso da Pesapal em cache e os IDs de notificação registrados são sempre removidos. As configurações e os logs do plugin (arquivos de log, incluindo os rotacionados, e registros de log no banco de dados da origem wcp_pesapal_pay) só são removidos se Delete data estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e IDs de rastreamento da Pesapal.

Pesapal é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado à Pesapal nem endossado por ela.