VibeFox Paymob 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.
Conta Paymob: uma conta de comerciante em um dos países compatíveis: Egito, Emirados Árabes Unidos, Arábia Saudita, Omã ou Paquistão. Você precisa de quatro valores do painel da Paymob: a chave de API, o ID de integração de uma integração de pagamento online, o ID do iFrame da página de pagamento e o segredo HMAC.
Moeda: a moeda da loja precisa ser a moeda do seu país Paymob: EGP para o Egito, AED para os Emirados Árabes Unidos, SAR para a Arábia Saudita, OMR para Omã e PKR para o Paquistão. Com outra moeda, o método de pagamento fica oculto na finalização de compra.
Chave de licença VibeFox: 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_paymob_pay para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Paymob > 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 no topo da página e clique em Activate.
5. Escolha o Paymob country e informe a chave de API, o ID de integração, o ID do iFrame e o segredo HMAC (veja Configuração).
6. No painel da Paymob, defina as URLs de callback da sua integração com a URL exibida na página de configurações (veja Callbacks).
7. Ative Enable/Disable. Teste um pagamento com o ID de uma integração de teste da Paymob e, depois, informe o ID da sua integração real.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Paymob. Acima dos campos, a página avisa quando um dos quatro valores da Paymob está faltando (até lá, a Paymob não aparece na finalização de compra) e quando a moeda da loja não é aceita pelo país Paymob selecionado. Uma caixa mostra a URL de callback com um botão Copy e um link para o painel da Paymob do país selecionado.
Geral
Enable/Disable: Enable Paymob 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: Paymob.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely by card or mobile wallet on the Paymob payment page.
Conta Paymob
Todos os valores estão no painel do seu cadastro de comerciante na Paymob. Não existe um modo de teste separado: para pagamentos de teste, informe o ID de integração de uma integração em modo de teste. Nenhuma outra configuração muda.
Paymob country: o país da sua conta Paymob. Ele define o servidor de API e de página de pagamento, e a moeda da loja precisa ser a moeda desse país. Padrão: Egypt.
API key: no painel da Paymob, em Settings > Account info > API Key.
Integration ID: no painel da Paymob, em Developers > Payment Integrations: o ID numérico da integração online de cartão ou carteira. Os métodos de pagamento oferecidos na página da Paymob são os desta integração.
iFrame ID: no painel da Paymob, em Developers > iframes: o ID numérico do iFrame de pagamento.
HMAC secret: no painel da Paymob, em Settings > Account info > HMAC. Obrigatório: os pedidos só são marcados como pagos por callbacks assinados com este segredo.
Integration ID e iFrame ID devem conter apenas dígitos. Os espaços são removidos. Qualquer outro valor é recusado ao salvar, com a mensagem de que o campo must contain digits only — the previous value was kept.
Callbacks
A Paymob informa cada transação à sua loja. No painel da Paymob, abra Developers > Payment Integrations, escolha a sua integração, clique em Edit e defina tanto Transaction processed callback quanto Transaction response callback com a URL exibida na página de configurações. Ela tem este formato: https://your-site/wc-api/paymob_pay/. Copie-a com o botão Copy. Defina as URLs em todas as integrações que você usa, inclusive a de teste.
O callback de transação processada é enviado pelo servidor da Paymob. O callback de resposta da transação traz o cliente de volta à sua loja. Ambos são assinados com o seu segredo HMAC e verificados pelo plugin. Callbacks sem assinatura válida são recusados e não alteram nada. Se o callback do servidor atrasar ou se perder, um retorno assinado do cliente também confirma o pagamento.
Avançado
Debug log: Log payment steps and callbacks grava as etapas do pagamento e os callbacks em WooCommerce > Status > Logs, origem wcp_paymob_pay. Erros e callbacks recusados são sempre registrados. Chaves, tokens e dados dos clientes nunca são gravados. Padrão: desativado.
Clean uninstall: Delete the plugin settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os IDs da Paymob salvos nos pedidos são mantidos. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Paymob) e faz o pedido. O plugin registra um novo pedido na Paymob pelo total do pedido, na moeda do pedido, envia à Paymob o nome, o e-mail, o telefone e o endereço de cobrança do cliente, e o encaminha à página de pagamento da Paymob do seu país. Lá, o cliente paga com um dos métodos da sua integração, por exemplo cartão ou carteira móvel.
Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago quando a Paymob confirma com uma transação assinada. Um pagamento realizado, pendente ou autorizado leva o cliente à página de pedido recebido.
Se o pagamento foi recusado, o cliente volta à finalização de compra (ou à página Pay for order, se o pagamento foi iniciado ali) com a mensagem Your Paymob payment was not completed. Please try again or choose another payment method. Cada nova tentativa registra um pedido próprio na Paymob, então o cliente pode refazer o mesmo pedido. Se o retorno da Paymob não puder ser verificado, o cliente vê We could not verify the response from Paymob. If you were charged, your order will be updated as soon as Paymob confirms the payment.
Se a Paymob não conseguir iniciar o pagamento, o cliente vê uma mensagem curta e pode escolher outro método de pagamento, por exemplo Paymob could not start the payment. Please check your billing details and try again, or choose another payment method. ou Could not connect to Paymob. Please try again in a moment. O motivo técnico é gravado 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. Na página Pay for order, verifica-se a moeda do pedido em vez da moeda da loja. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita pagamentos únicos na página da Paymob. Não há cartões salvos, assinaturas, formulário de cartão incorporado ao seu site nem reembolsos pelo WooCommerce.
Pedidos
Status do pedido
Pending payment: o cliente foi enviado à Paymob e ainda não pagou, ou a Paymob ainda não confirmou o pagamento.
Processing: a Paymob confirmou o pagamento. Pedidos com apenas produtos virtuais para download passam para Concluído, o padrão do WooCommerce. A nota do pedido mostra a transação da Paymob, o valor e o tipo de cartão com os quatro últimos dígitos. O ID da transação é o ID de transação da Paymob.
On hold: o pagamento está pendente na Paymob, por exemplo um pagamento em dinheiro ou em totem; ou a Paymob apenas autorizou o valor e não o capturou (capture-o no painel da Paymob; o pedido é concluído quando chega o callback de captura); ou o valor ou a moeda pagos diferem do pedido; ou chegou um pagamento para um pedido cancelado. A nota do pedido explica o motivo.
Failed: a Paymob recusou o pagamento de um pedido pendente. O cliente pode pagar novamente.
Se chegar um segundo pagamento bem-sucedido para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse o duplicado no painel da Paymob. Um pagamento para um pedido cancelado que já havia sido pago, ou para um pedido reembolsado, apenas adiciona uma nota: o pedido não é reaberto.
Reembolsos
Reembolsos pelo WooCommerce não são suportados. Reembolse ou anule o pagamento no painel da Paymob. Quando a Paymob informa um reembolso ou uma anulação, uma nota é adicionada ao pedido, e o status do pedido não muda. Atualize o pedido manualmente, por exemplo com 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 no topo de WooCommerce > Settings > Payments > Paymob. 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 o seu domínio. Use Check now para verificar o status de novo, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta na 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 na sua conta vibefox.net.
Sem uma chave ativa, a Paymob 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. Os gerentes da loja que estiverem 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 aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.
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 Paymob não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se os quatro valores (API key, Integration ID, iFrame ID, HMAC secret) estão preenchidos e se a moeda da loja é a do Paymob country selecionado. A página de configurações mostra um aviso quando algo está faltando. Desenvolvedores com uma conta Paymob de várias moedas podem ampliar as moedas aceitas com o filtro paymob_p_supported_currencies.
O pagamento foi feito, mas o pedido continua em Pending payment: os callbacks não chegam à sua loja. Confira se o Transaction processed callback e o Transaction response callback da integração usada são exatamente a URL exibida na página de configurações, e se o HMAC secret é o da mesma conta Paymob. Callbacks recusados são registrados como avisos em WooCommerce > Status > Logs, origem wcp_paymob_pay, mesmo com o log de depuração desativado.
O callback responde Invalid signature: o segredo HMAC nas configurações não corresponde à conta Paymob, ou a conta de outro país está selecionada. Copie o segredo HMAC novamente.
O callback responde Not configured: o segredo HMAC está vazio. Informe o segredo; a Paymob repetirá o callback.
O callback responde locked: o pedido estava sendo atualizado por outra requisição ao mesmo tempo, por exemplo o retorno do cliente. A Paymob repetirá o callback.
O cliente vê um erro ao fazer o pedido: ative o Debug log e consulte o registro. Paymob payments are temporarily unavailable indica uma chave de API incorreta ou um valor faltando. Paymob could not start the payment indica que a Paymob recusou a requisição, por exemplo por um ID de integração incorreto ou dados de cobrança incompletos. This order cannot be paid with Paymob indica que o total do pedido é zero.
O pedido fica em On hold depois do pagamento: leia a nota do pedido. O pagamento está pendente (dinheiro ou totem), a transação foi apenas autorizada (capture-a no painel da Paymob), o valor ou a moeda não correspondiam, ou o pagamento chegou depois de o pedido ser cancelado. A nota do pedido explica o motivo.
Pagamentos de teste: informe o ID de uma integração de teste da Paymob em Integration ID e defina os callbacks nessa integração. Para pagamentos reais, informe novamente o ID da sua integração real.
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 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-o e exclua-o na página Plugins. A chave de licença e o status da licença deste plugin são sempre removidos. As configurações do gateway e os logs só são removidos se Clean uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e IDs da Paymob.
A Paymob é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Paymob.