VibeFox Paymob for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Conta Paymob: uma conta de comerciante em um dos países suportados: 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 pagamentos online, o ID do iFrame da página de pagamento e o segredo HMAC.

Moeda: a moeda da finalização de compra 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ã, PKR para o Paquistão. Adicione-a em System > Localisation > Currencies se a sua loja ainda não a tiver. Com outra moeda, o método de pagamento fica oculto na finalização de compra. Contas Paymob multimoeda não são suportadas.

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_paymob_pay-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_paymob_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, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_paymob_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ê pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Paymob Pay e clique em Install (o botão verde +).

3. Clique em Edit (o botão de 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 Chave de licença).

4. 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).

5. No painel da Paymob, defina as URLs de callback da sua integração como a URL exibida na seção Callbacks (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 de produção.

OpenCart 4

1. No painel administrativo, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_paymob_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 nesta mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Paymob Pay, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença, as chaves e IDs da Paymob e as URLs de callback como nos passos 3 a 6 do OpenCart 3. A página de configurações e seus campos são os mesmos nas duas versões. Só a URL de callback é diferente (veja Callbacks).

Uma instalação nova começa com o método de pagamento desativado.

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox Paymob Pay > Edit. As seções aparecem à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, a página avisa quando um dos quatro valores da Paymob está faltando (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.

Ao salvar, Title não pode ter mais de 128 caracteres, Sort Order precisa ser um número inteiro (números negativos são permitidos), Total precisa ser um número igual ou maior que 0, e a zona geográfica e os status de pedido selecionados precisam existir; caso contrário, nada é salvo e a página indica o campo.

Paymob

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. Também é o nome do método de pagamento salvo no pedido, até 128 caracteres. Se estiver vazio, os clientes veem Paymob. Padrão: Paymob.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely by card or mobile wallet on the Paymob payment page. Deixe em branco para não exibir texto.

Sort Order: a posição da Paymob entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferecer a Paymob somente para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones. No OpenCart 4, quando a loja não pede endereço de pagamento, o endereço de entrega é usado.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que a Paymob seja oferecida. Deixe em branco para oferecer a Paymob com qualquer total.

Conta Paymob

Todos os valores estão no painel de comerciante da Paymob. Não há 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 da API e da página de pagamento, e a moeda da finalização de compra 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. 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 chave de API e o segredo HMAC salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo. Para remover um valor salvo, marque Clear the saved API key on save ou Clear the saved HMAC secret on save abaixo do campo e clique em Save.

Callbacks

A Paymob informa à sua loja cada transação. No painel da Paymob, abra Developers > Payment Integrations, escolha a sua integração, clique em Edit e defina tanto o Transaction processed callback quanto o Transaction response callback como a Callback URL exibida nesta seção. No OpenCart 3 ela tem este formato: https://your-store/index.php?route=extension/payment/wcp_paymob_pay/callback; no OpenCart 4: https://your-store/index.php?route=extension/wcp_paymob_pay/payment/wcp_paymob_pay.callback. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. Copie-a com o botão Copy. A seção também traz um link para o painel da Paymob do país selecionado. Defina as URLs em cada integração que você usar, inclusive na 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 segredo HMAC e verificados pela extensão. Callbacks sem assinatura válida são recusados e não alteram nada. Se o callback do servidor chegar atrasado ou se perder, um retorno assinado do cliente também confirma o pagamento. A URL de callback também funciona enquanto a loja está em manutenção: o OpenCart 3 deixa passar as requisições das extensões de pagamento, e no OpenCart 4 a extensão adiciona uma ação de inicialização (startup) que deixa passar os callbacks e o retorno do cliente.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele só recebe um status depois que a Paymob informa uma transação corretamente assinada. Um pagamento recusado deixa o pedido sem status; o cliente volta à finalização de compra com o carrinho mantido. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: a transação da Paymob está paga com o valor e a moeda esperados. Padrão: Processando.

Awaiting Paymob Payment Status: a transação está pendente, por exemplo um pagamento em dinheiro ou em quiosque. O pedido recebe o status pós-pagamento quando a Paymob confirma. Padrão: Pendente.

Paymob Payment On Hold Status: a Paymob apenas autorizou o valor (capture-o no painel da Paymob), o valor ou a moeda pagos diferem do pedido, ou o pagamento chegou para um pedido cancelado. Uma nota explica o motivo. Padrão: Pendente, porque o OpenCart não tem o status On hold. Você pode criar o seu próprio status em System > Localisation > Order Statuses e selecioná-lo aqui.

Os três campos seguintes informam à extensão quais status a sua loja usa. A extensão nunca os define.

Payment Error Status: o status que a sua loja usa para pedidos com erro de pagamento. Uma transação pendente pode levar um pedido desses ao status de espera. Padrão: Falhou.

Cancelled Order Status: o status que a sua loja usa para pedidos cancelados. Um pagamento recebido para um pedido desses o coloca em retenção, ou apenas acrescenta uma nota se ele já tiver sido pago antes. Padrão: Cancelado.

Refunded Order Status: o status que a sua loja usa para pedidos reembolsados. Um pagamento recebido para um pedido desses apenas acrescenta uma nota. Padrão: Reembolsado.

Avançado

Debug log: grava as etapas do pagamento e os callbacks em paymob_p_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Erros e callbacks recusados são sempre registrados, mesmo com a opção desligada. Chaves, tokens e dados de clientes nunca são gravados. Padrão: desativado.

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

Clean uninstall: quando ativado, desinstalar a extensão apaga as configurações do gateway e o log. Os IDs da Paymob salvos para os pedidos (tentativas de pagamento) são sempre mantidos. Padrão: desativado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. A chave de API e o segredo HMAC não são exportados.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. Os segredos salvos são mantidos.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Paymob). Na etapa Confirm Order, o cliente vê a sua descrição e a nota You will be redirected to the secure Paymob payment page to pay by card or mobile wallet. 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 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 (no OpenCart 4, quando a loja não pede endereço de pagamento, o endereço de entrega) e o encaminha para a 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 para a sua loja. O pedido só é marcado como pago quando a Paymob o confirma com uma transação assinada. Então o pedido recebe o seu status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Um pagamento pendente (por exemplo, em dinheiro ou em quiosque) ou um pagamento autorizado também dá um status ao pedido, o de espera ou o de retenção, e leva à página de sucesso.

Se o pedido ainda estiver sendo confirmado quando o cliente volta, uma página Payment confirmation mostra 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 o seu próprio pedido na Paymob, então o cliente pode pagar o carrinho novamente. O OpenCart 3 cria um pedido novo sempre que a etapa Confirm Order é exibida; o OpenCart 4 mantém um pedido para a finalização de compra e o atualiza, então o cliente paga o mesmo pedido com uma nova tentativa. 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 outro pedido do mesmo carrinho já tiver sido pago ou estiver aguardando pagamento (por exemplo, em uma segunda aba do navegador), o cliente é levado à página de sucesso em vez de pagar de novo. No OpenCart 4, as mensagens após o retorno da Paymob são exibidas acima da página de finalização de compra.

O OpenCart 4 mantém o pedido na finalização de compra até que a página de sucesso seja exibida. Se esse pedido foi fechado sem pagamento nesse meio tempo (por exemplo, você o cancelou), o cliente volta à finalização de compra com Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., e o próximo Confirm Order paga um pedido novo. Se esse pedido já tiver um status e o carrinho agora tiver outros produtos ou quantidades, o cliente também volta à finalização de compra, e o novo carrinho recebe um pedido novo.

Se a Paymob não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma mensagem curta acima do botão, 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.

A extensão aceita apenas 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 painel administrativo.

Pedidos

Status do pedido

No status (missing order): o cliente foi enviado à Paymob e não pagou, o pagamento foi recusado, ou a Paymob ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

No OpenCart 4, um pedido não pago da finalização de compra pode receber o status Voided, que o OpenCart 4 define quando o cliente volta à etapa Confirm Order. A extensão trata esse pedido como um pedido sem status, e um pagamento posterior ainda o confirma.

Order Status After Payment (default Processing): a Paymob confirmou o pagamento. Uma nota mostra a transação, o valor e o tipo de cartão com os quatro últimos dígitos.

Awaiting Paymob Payment Status (default Pending): o pagamento está pendente na Paymob, por exemplo um pagamento em dinheiro ou em quiosque. O pedido passa para o status pós-pagamento quando a Paymob confirma o pagamento.

Paymob Payment On Hold Status (default Pending): a Paymob apenas autorizou o valor e não o capturou (capture-o no painel da Paymob; o pedido passa para o status pós-pagamento quando chegar o callback de captura); ou o valor ou a moeda pagos não correspondem ao pedido; ou chegou um pagamento para um pedido que havia sido cancelado. A nota explica o motivo. Verifique o pedido e atenda-o ou reembolse o pagamento no painel da Paymob.

Quando um pedido que já tem um status muda, o OpenCart avisa o cliente. Se chegar um segundo pagamento bem-sucedido para um pedido já pago, ou um pagamento para um segundo pedido de um carrinho já pago, o pedido pago não muda e uma nota pede que você reembolse o duplicado no painel da Paymob. Um pagamento para um pedido cancelado que havia sido pago antes, ou para um pedido reembolsado, apenas acrescenta uma nota: o pedido não é reaberto. Um pagamento recusado para um pedido que já tem um status apenas acrescenta uma nota.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox Paymob Pay

Em Sales > Orders, abra um pedido pago com a Paymob. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Paymob Pay mostra cada tentativa da Paymob do pedido: o Paymob order com o ID do pedido do comerciante e o país, o Paymob transaction ID, o Status, o valor Requested, o Amount reported by Paymob com o cartão e a Paymob message. Abaixo ficam as Notes da extensão para este pedido. A aba é mostrada aos usuários que têm acesso à extensão.

Reembolsos

Reembolsos pelo painel administrativo 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 é acrescentada ao pedido, e o status do pedido não muda. Atualize o pedido manualmente.

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 Paymob Pay é o primeiro bloco em Extensions > Extensions > Payments > VibeFox Paymob Pay > 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 ficam a linha Product: opencart-payment-paymob e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Apenas usuários administradores com a permissão Modify da 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 alterar 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 domínio: o endereço da loja da configuração do OpenCart. 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. Um usuário administrador conectado ao painel administrativo no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), 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 do administrador, 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 do painel administrativo. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática quando você abre o Dashboard ou a página Edit do painel administrativo: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário um cron job. Desinstalar a extensão 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 Enable/Disable está ativado, se os quatro valores (chave de API, ID de integração, ID do iFrame, segredo HMAC) estão preenchidos e se a moeda da finalização de compra é a do Paymob country selecionado. A página de configurações mostra um aviso quando algo está faltando. Verifique 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: os callbacks não estão chegando à 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 seção Callbacks, e se o HMAC secret é o da mesma conta Paymob. Callbacks recusados são gravados no log como avisos, mesmo com o Debug log desativado. Veja o campo Log na página da extensão.

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 repete o callback.

O 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 status do pedido não pôde ser definido. A Paymob repete o callback. O motivo é gravado no log.

Abrir a URL de callback no navegador leva à finalização de compra com a mensagem de que não foi possível verificar: isso é normal. A URL aceita apenas requisições assinadas pela Paymob.

O cliente vê um erro depois de Confirm Order: ative o Debug log e consulte o log. Paymob payments are temporarily unavailable significa uma chave de API errada ou um valor faltando. Paymob could not start the payment significa que a Paymob recusou a requisição, por exemplo por um ID de integração errado ou dados de cobrança incompletos. This order cannot be paid with Paymob significa que o total do pedido é zero. Paymob does not accept payments in seguido de uma moeda significa que a moeda do pedido não é a do país Paymob selecionado. This payment method is not available. significa que a sessão da finalização de compra não corresponde mais ao pedido ou que o método de pagamento foi desativado nesse meio tempo: o cliente recarrega a finalização de compra.

O pedido está no status de retenção ou de espera depois do pagamento: leia as notas na aba VibeFox Paymob Pay. O pagamento está pendente (dinheiro ou quiosque), 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 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 de produção.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Paymob Pay. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as configurações próprias da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos padrões em uma nova instalação. No OpenCart 4 também são removidos o evento do OpenCart da extensão e a sua ação de inicialização, que deixa passar os callbacks e o retorno do cliente em modo de manutenção. Se Clean uninstall estiver ativado, as demais configurações do gateway (título, descrição, país, chaves e IDs, registro) e o log são removidos. Se estiver desativado, eles são mantidos para uma nova instalação. As tentativas de pagamento da Paymob dos pedidos são sempre mantidas. Os pedidos existentes mantêm as suas notas de pagamento e os IDs da Paymob.

No OpenCart 4, para remover também os arquivos da extensão, acesse Extensions > Installer após a desinstalação, clique em Uninstall (o botão laranja −) ao lado de VibeFox Paymob Pay na lista de extensões instaladas e depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

A Paymob é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela Paymob.