VibeFox Paymob 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.

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 API key, o integration ID de uma integração de pagamento online, o iFrame ID da página de pagamento e o HMAC secret.

Moeda: a moeda do carrinho deve 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ã, PKR para o Paquistão. Com outra moeda, o método de pagamento fica oculto na finalização de compra. Contas Paymob com várias moedas não são compatíveis.

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 encontre depois o VibeFox Paymob Pay na lista de módulos e clique em Configure.

3. Informe a 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. Escolha o Paymob country e informe a API key, o integration ID, o iFrame ID e o HMAC secret (veja Configuração).

5. No painel da Paymob, defina as URLs de callback da sua integração como a URL exibida na página Configure (veja Callbacks).

6. Ative Enable/Disable e clique em Save. Teste um pagamento com o ID de uma integração de teste da Paymob e, depois, informe o ID da sua integração real.

Na instalação, o módulo cria dois status de pedido: Awaiting Paymob payment e Paymob payment on hold. Por padrão, o PrestaShop ativa um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-los em Payment > Preferences. Um país que você ativar na loja mais tarde também deve estar marcado ali para este módulo.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Paymob Pay > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa quando falta um dos quatro valores da Paymob (até lá, a Paymob fica oculta na finalização de compra) e quando a moeda padrão da loja não é aceita pelo país Paymob selecionado. Uma caixa Callbacks mostra a URL de callback com um botão Copy e um link para o painel da Paymob do país selecionado.

Paymob

Enable/Disable: Enable Paymob 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: 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. Deixe vazio para não exibir texto.

Conta Paymob

Todos os valores estão no painel de comerciante da sua conta Paymob. Não há modo de teste separado: para pagamentos de teste, informe o integration ID de uma integração em modo de teste. Nenhuma outra configuração muda.

Paymob country: o país da sua conta Paymob. Ele seleciona o servidor de API e de página de pagamento, e a moeda do carrinho deve 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 criados como pagos a partir de callbacks assinados com este segredo.

O integration ID e o iFrame ID devem conter apenas dígitos. 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. Os demais campos são salvos.

A API key e o HMAC secret salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.

Clear saved secrets: marque API key ou HMAC secret e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

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 caixa Callbacks. Com URLs amigáveis, ela fica assim: https://your-shop/module/wcp_paymob_pay/callback, possivelmente com um código de idioma como /en/. A URL é gerada no idioma padrão da loja. Copie-a com o botão Copy. Defina as URLs em todas as integrações que você usa, inclusive a de teste.

O transaction processed callback é enviado pelo servidor da Paymob. O transaction response callback traz o cliente de volta à sua loja. Ambos são assinados com o seu HMAC secret e verificados pelo módulo. Callbacks sem assinatura válida são recusados e não alteram nada. Se o callback de servidor atrasar ou se perder, um retorno assinado do cliente também confirma o pagamento. O callback de servidor funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

Avançado

Debug log: grava as etapas de pagamento e os callbacks em logs/paymob_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e callbacks recusados são sempre registrados, mesmo quando a opção está desligada. Chaves, tokens e dados dos clientes nunca são gravados. Padrão: desligado.

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

Clean uninstall: quando ativado, desinstalar o módulo apaga as configurações e os logs do módulo. Os IDs da Paymob salvos para os pedidos (tentativas de pagamento) e os status de pedido são sempre mantidos. Padrão: desligado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Paymob) e confirma. O módulo registra um novo pedido na Paymob pelo total do carrinho na moeda do carrinho, 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 digital. Neste ponto, ainda não existe pedido.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago depois que a Paymob o confirma com uma transação assinada. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Um pagamento pendente (por exemplo, em dinheiro ou em totem) ou um pagamento autorizado também cria o pedido, em um status de espera, e leva à página de confirmação.

Se o pedido estiver sendo confirmado pelo callback da Paymob no mesmo momento, o cliente vê uma página com Paymob accepted your payment and we are confirming it. You will receive an e-mail as soon as your order is confirmed — there is no need to pay again. Para um pagamento pendente, o texto é Your Paymob payment is pending (for example a cash or kiosk payment). Complete it as Paymob instructed you: your order is confirmed as soon as Paymob reports the payment. A página tem um botão Check again e um botão Back to checkout.

Se o pagamento foi recusado, o cliente volta à finalização de compra com o mesmo carrinho e 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 pagar o carrinho novamente. Se a resposta da Paymob não puder ser verificada, 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 permanece na finalização de compra com uma mensagem curta, 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ódulo 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 back office.

Pedidos

Status do pedido

No order yet: o cliente foi enviado à Paymob e não pagou, o pagamento foi recusado ou a Paymob ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: a Paymob confirmou o pagamento. O pagamento é registrado com o ID da transação da Paymob como ID da transação, e uma nota mostra a transação, o valor e o tipo de cartão com os quatro últimos dígitos.

Awaiting Paymob payment: o pagamento está pendente na Paymob, por exemplo um pagamento em dinheiro ou em totem. O pedido passa para Payment accepted quando a Paymob confirma o pagamento.

Paymob payment on hold: a Paymob apenas autorizou o valor e não o capturou (capture-o no painel da Paymob; o pedido passa para Payment accepted quando chega o callback de captura); ou o valor ou a moeda pagos diferem do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou); ou chegou um pagamento para um pedido cancelado. A nota explica o motivo. Verifique o pedido e atenda-o ou reembolse o pagamento no painel da Paymob.

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á tinha sido pago, ou para um pedido reembolsado, apenas adiciona uma nota: o pedido não é reaberto. Um pagamento recusado para um pedido que ainda não está pago apenas adiciona uma nota.

Bloco de pagamento da Paymob

A página do pedido mostra um bloco Paymob payment com cada tentativa de pagamento da Paymob do pedido: o pedido na Paymob, o ID do pedido do comerciante e o país, o ID da transação da Paymob, o status, o valor solicitado, o valor informado pela Paymob com o cartão e a mensagem da Paymob. Abaixo ficam as Notes do módulo para este pedido.

Reembolsos

Reembolsos pelo back office não são suportados. Reembolse ou cancele o pagamento no painel da Paymob. Quando a Paymob informa um reembolso ou um cancelamento, uma nota é adicionada ao pedido, e o status do pedido não muda. Atualize o pedido manualmente, por exemplo o seu status, ou com uma nota de crédito.

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 Paymob Pay é o primeiro bloco de Modules > Module Manager > VibeFox Paymob Pay > Configure, acima das configurações. Insira 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-paymob e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente funcionários com a permissão Configure para o 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 vibefox.net.

Sem uma chave ativa, a Paymob não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, o cliente vê This payment method is not available. Please choose another one. A vitrine do PrestaShop não sabe que você está logado no 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.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 Paymob não aparece na finalização de compra: verifique se a licença está ativa, se o Enable/Disable está ligado, se os quatro valores (API key, integration ID, iFrame ID, HMAC secret) estão preenchidos e se a moeda do carrinho é a moeda do Paymob country selecionado. A página de configurações mostra um aviso quando algo está faltando. 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.

O pagamento foi aprovado, mas nenhum pedido foi criado: os callbacks não chegam à sua loja. Verifique se o Transaction processed callback e o Transaction response callback da integração que você usa são exatamente a URL exibida na caixa Callbacks, e se o HMAC secret é o da mesma conta Paymob. Os callbacks recusados são gravados no log como avisos, mesmo quando o Debug log está desligado. Veja o campo Log na página do módulo.

Callback responde Invalid signature: o HMAC secret nas configurações não corresponde à conta da Paymob, ou está selecionada a conta de outro país. Copie novamente o HMAC secret.

Callback responde Not configured: o HMAC secret está vazio. Informe o segredo; a Paymob vai repetir o callback.

Callback responde locked ou retry: o pedido estava sendo atualizado por outra requisição no mesmo momento, por exemplo o retorno do cliente, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Paymob vai repetir o callback. O motivo é gravado no log.

Abrir a URL do callback no navegador leva à finalização de compra com a mensagem could not verify: isso é normal. A URL aceita apenas requisições assinadas pela Paymob.

O cliente vê um erro ao escolher a Paymob: ative o Debug log e consulte o log. Paymob payments are temporarily unavailable indica uma API key errada ou um valor ausente. Paymob could not start the payment indica que a Paymob recusou a requisição, por exemplo por um integration ID errado ou dados de cobrança incompletos. This order cannot be paid with Paymob indica que o total do pedido é zero. Paymob does not accept payments in seguido de uma moeda indica que a moeda do carrinho não é a moeda do país Paymob selecionado.

O pedido está em Paymob payment on hold ou em Awaiting Paymob payment após o pagamento: leia as notas no bloco Paymob payment. 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 coincidiram, ou o pagamento chegou depois que o pedido foi cancelado.

Pagamentos de teste: informe o ID de uma integração de teste da Paymob em Integration ID e defina as URLs de callback nessa integração. Para pagamentos reais, informe novamente o ID da sua integração real.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Paymob Pay e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se o Clean uninstall estiver ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As tentativas de pagamento da Paymob dos pedidos e os status de pedido Awaiting Paymob payment e Paymob payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e IDs da Paymob.

A Paymob é uma marca de seu respectivo titular. Este módulo não é afiliado à Paymob nem endossado por ela.