VibeFox PayPlug for OpenCart — Ajuda

Requisitos

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

PHP: 8.0 ou superior.

Moeda e valores: euro (EUR), de 0,99 a 20.000,00 por pagamento, os padrões da PayPlug. O euro deve estar habilitado em System > Localisation > Currencies e ser selecionado pelo cliente. Com outra moeda de finalização de compra ou fora desses limites, o método de pagamento fica oculto.

Conta na PayPlug: você precisa das chaves secretas da sua conta na PayPlug: a chave de teste (sk_test_...) e/ou a chave de produção (sk_live_...). Nenhuma outra chave é necessária, e nenhuma notificação precisa ser configurada na PayPlug. A sua loja precisa estar acessível pela internet para receber as notificações; caso contrário, os pedidos são confirmados quando o cliente volta da PayPlug.

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_payplug_gateway-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_payplug_gateway.ocmod.zip. Instale somente 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_payplug_gateway-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, por isso 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. Localize VibeFox PayPlug Gateway e clique em Install (o botão verde +). O seu usuário administrador precisa do direito de modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Informe 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. Cole as suas chaves secretas do portal da PayPlug (veja Configuração).

5. Ative Enable/Disable e clique em Save. Teste um pagamento com Test Mode ativado e depois desative-o para aceitar pagamentos reais.

OpenCart 4

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

3. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox PayPlug Gateway, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença e as chaves secretas da PayPlug como nos passos 3 a 5 do OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Apenas a URL de notificação é diferente (veja Notificações).

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

Configuração

Todas as configurações ficam na página da extensão: Extensions > Extensions > Payments > VibeFox PayPlug Gateway > 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 o método de pagamento está ativado, mas a chave secreta do modo atual está vazia, e quando a moeda padrão da loja não é EUR. Nos dois casos, o método de pagamento fica oculto na finalização de compra (com outra moeda padrão, enquanto essa moeda estiver selecionada). Sem o direito de modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title deve ter de 1 a 128 caracteres, Sort Order deve ser um número inteiro, Total deve ser um número igual ou maior que 0 e os status de pedido precisam existir; caso contrário, nada é salvo e a página lista os erros. Uma chave secreta com formato incorreto não é salva, mas as demais configurações são: a página mostra Settings saved, except the secret key shown in red. e, por exemplo, Test Secret Key must start with "sk_test_". The previous value was kept.

Checkout

Enable/Disable: Enable PayPlug Gateway 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. Ele também é o nome do método de pagamento salvo no pedido. Padrão: PayPlug. Obrigatório, até 128 caracteres.

Description: o texto exibido ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely by card via PayPlug.

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

Geo Zone: oferecer a PayPlug 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.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que a PayPlug seja oferecida. Deixe em branco para oferecer a PayPlug em qualquer total. A própria PayPlug aceita de 0,99 a 20.000,00 EUR por pagamento.

Chaves de API

Encontre as suas chaves secretas no portal da PayPlug, em Developers > API keys. A seção tem um link para o portal.

Test Mode: usa a chave secreta de teste para os novos pagamentos. Nenhum pagamento real é processado. Os pagamentos feitos no outro modo continuam usando a chave do próprio modo para verificação de status e reembolsos. Padrão: ligado. Enquanto estiver ligado, o cliente vê Test mode: no real payment will be made. na etapa Confirm Order.

Test Secret Key: a sua chave secreta de teste da PayPlug. Começa com sk_test_.

Live Secret Key: a sua chave secreta de produção da PayPlug. Começa com sk_live_.

As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para remover uma chave salva, marque Clear the saved key on save abaixo do campo e clique em Save.

Notificações

Notification URL: o endereço que a extensão envia à PayPlug com cada pagamento. No OpenCart 3 ele tem este formato: https://your-store/index.php?route=extension/payment/wcp_payplug_gateway/webhook, e no OpenCart 4: https://your-store/index.php?route=extension/wcp_payplug_gateway/payment/wcp_payplug_gateway.webhook. Ele é montado a partir do endereço da vitrine da sua instalação do OpenCart. Não é preciso informar nada no portal da PayPlug. Cada notificação é verificada relendo o pagamento pela API da PayPlug, por isso os pagamentos são confirmados mesmo quando o cliente não volta para a loja. A URL precisa estar acessível pela internet; caso contrário, os pedidos só são confirmados quando o cliente volta da PayPlug.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois que a PayPlug informa o pagamento, pela notificação ou pelo retorno do cliente; o pagamento é sempre relido na PayPlug. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: o status definido após um pagamento bem-sucedido, por exemplo Processing ou Complete. Padrão: Processing.

PayPlug Payment On Hold Status: o pagamento precisa da sua análise (veja Status do pedido). Padrão: Pending, 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.

Payment Error Status: o pagamento autorizado de um pedido em espera falhou ou foi cancelado. Padrão: Failed.

Refunded Status: definido depois que o pagamento é totalmente reembolsado pela página do pedido. Padrão: Refunded.

Avançado

Logging: registra as chamadas à API e as notificações em ppg_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Chaves secretas, dados de cartão e dados do cliente nunca são registrados. Padrão: desligado.

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

Delete Data on Uninstall: quando ligado, ao desinstalar a extensão suas configurações e seu log são excluídos. Os registros de pagamentos e reembolsos da PayPlug dos pedidos são sempre mantidos. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves secretas não são exportadas.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves secretas salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, PayPlug). Na etapa Confirm Order, o cliente vê a sua descrição e a observação You will be redirected to the secure PayPlug payment page to pay by card.; no modo de teste, também Test mode: no real payment will be made. 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 na parte inferior da página de finalização de compra. Quando o cliente clica em Confirm Order, a extensão cria um pagamento na PayPlug pelo total do pedido em centavos e envia o cliente para a página de pagamento da PayPlug. Os endereços de cobrança e de entrega, o e-mail e o idioma do pedido são passados à PayPlug. Lá, o cliente paga com cartão.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a PayPlug o confirma: a extensão relê o pagamento pela API da PayPlug quando a notificação chega e quando o cliente volta. Em seguida, 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 com Your payment with PayPlug has been received. Se o pedido estiver em espera, a página diz We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Se o pedido estiver no status de erro de pagamento, a página diz Your PayPlug payment was not completed. Please contact us about this order. Se não foi possível consultar a PayPlug quando o cliente voltou, uma página Payment confirmation mostra o mesmo texto de «estamos confirmando» e um botão Check again; a notificação define o status do pedido assim que chegar.

Se o cliente cancelar na página da PayPlug, a página de pagamento é fechada na PayPlug, para que não possa ser paga depois por engano. O cliente volta à finalização de compra com uma mensagem: You cancelled the PayPlug payment. You can try again or choose another payment method., The PayPlug payment session has expired. Please try again or choose another payment method., The PayPlug payment failed. Please try again or choose another payment method. ou, se o pagamento tiver ficado aberto, Your PayPlug payment was not completed. You can try again or choose another payment method. O carrinho é mantido. No OpenCart 4, essas mensagens são exibidas acima da página de finalização de compra.

O OpenCart 3 cria um novo pedido sempre que a etapa Confirm Order é exibida, e o OpenCart 4 atualiza o pedido da finalização de compra (uma nova tentativa é um novo pagamento na PayPlug para o mesmo pedido), por isso a extensão verifica primeiro as tentativas anteriores do mesmo carrinho. Se uma delas tiver sido paga nesse meio-tempo, esse pagamento é usado sem criar outro e o cliente vai para a página de sucesso. Se a tentativa deste pedido ainda estiver aberta pelo mesmo valor, a mesma página de pagamento é reutilizada. Caso contrário, a página antiga é fechada na PayPlug e um novo pagamento é criado. Um pagamento tardio feito em uma página fechada ainda é registrado. Uma alteração do carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de um pagamento próprio.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio-tempo (por exemplo, você o cancelou ou o pagamento autorizado falhou), o cliente volta à finalização de compra com a mensagem Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order. O próximo Confirm Order paga um novo pedido. Se esse pedido já tiver sido pago por um carrinho anterior e o carrinho tiver mudado desde então, o cliente volta à finalização de compra, e o próximo Confirm Order paga um novo pedido do carrinho atual. Um pedido fechado nunca é exibido como pago.

Se a PayPlug não conseguir iniciar o pagamento, o cliente permanece na etapa Confirm Order com uma mensagem curta, por exemplo PayPlug could not accept your billing details (postcode). Please check them and try again. ou The payment provider could not be reached. Please try again in a moment. O motivo técnico é gravado no log.

A notificação também funciona enquanto a loja está em modo de manutenção, porque o OpenCart deixa passar as requisições das extensões de pagamento (no OpenCart 4, a extensão adiciona para isso uma ação de inicialização própria, que também deixa passar o retorno do cliente da PayPlug).

Os pagamentos são cobrados imediatamente. A extensão não tem parcelamento Oney, cartões salvos com um clique, formulário de pagamento incorporado, assinaturas nem captura adiada.

Pedidos e reembolsos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado à PayPlug e não pagou, ou a PayPlug ainda não confirmou o pagamento. Em Sales > Orders, esses pedidos aparecem somente com o filtro Order Status definido como Missing Orders. Se o pagamento falhar, a tentativa é encerrada e o cliente pode pagar novamente.

Order Status After Payment (padrão Processing): o pagamento foi confirmado. Uma observação mostra o pagamento da PayPlug e o seu modo.

PayPlug Payment On Hold Status (padrão Pending): o valor ou a moeda pagos diferem do pedido (observação amount/currency mismatch); ou um pagamento de teste foi feito enquanto a loja estava em produção, então nenhum dinheiro foi recebido; ou o pagamento chegou depois que o pedido recebeu outro status, por exemplo se ele foi cancelado; ou um pagamento está autorizado, mas não capturado (capture-o no portal da PayPlug; o pedido é marcado como pago quando a PayPlug informa que foi pago). A observação explica o que verificar.

Payment Error Status (padrão Failed): um pagamento autorizado de um pedido em espera falhou ou foi cancelado. O OpenCart notifica o cliente sobre essa mudança.

Refunded Status (padrão Refunded): o pagamento foi totalmente reembolsado pela extensão.

Se outro pedido de um carrinho já pago também for pago, esse pedido continua sem status e o pedido pago não é alterado. Uma observação no pedido pago pede que você reembolse o pagamento duplicado no portal da PayPlug. Um pedido pago ou reembolsado nunca é reaberto por uma notificação posterior.

As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox PayPlug Gateway

Em Sales > Orders, abra um pedido pago com a PayPlug. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox PayPlug Gateway mostra o PayPlug payment ID com o rótulo Test mode para pagamentos de teste, o Status do pagamento, os valores Paid / refunded, o formulário de reembolso, o histórico de reembolsos (com o modo de cada um) e as PayPlug notes do pedido. A aba é exibida aos usuários que têm acesso à extensão.

Reembolsos

Na aba VibeFox PayPlug Gateway, informe o Amount (o valor ainda não reembolsado já vem preenchido), opcionalmente um Reason (optional), e clique em Refund via PayPlug. Confirme a pergunta Refund this amount through PayPlug? This cannot be undone. São aceitos reembolsos totais e parciais. Você precisa do direito de modificar a extensão (definido em System > Users > User Groups). Os reembolsos são feitos até o valor que a PayPlug efetivamente cobrou, então, após uma divergência de valor, você pode reembolsar o que o cliente pagou, e não o total do pedido. O reembolso é feito no pagamento que de fato quitou o pedido, com a chave secreta do modo (teste ou produção) em que ele foi feito; por isso essa chave precisa estar configurada. Se a PayPlug não aceitar o reembolso, a aba mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às observações, com o ID do reembolso da PayPlug e o motivo. Um reembolso total define o Refunded Status no pedido sem notificar o cliente e sem devolver produtos ao estoque, como uma alteração manual de status. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a PayPlug informa o pagamento como pago.

As devoluções de produtos em Sales > Returns não devolvem dinheiro pela PayPlug.

Os reembolsos feitos no portal da PayPlug chegam por notificação e são adicionados às observações uma única vez. Eles aparecem no histórico de reembolsos, mas não são contados como reembolsos da extensão e não alteram o status do pedido. Registre-os manualmente, se necessário.

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 PayPlug Gateway é o primeiro bloco em Extensions > Extensions > Payments > VibeFox PayPlug Gateway > Edit, 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, aparecem a linha Product: opencart-payment-payplug e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Somente usuários administradores com a permissão Modify para a 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 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja nas configurações 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 PayPlug 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. 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 que você 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 e os reembolsos funcionam.

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 ao abrir o Dashboard do painel administrativo ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é preciso nenhum cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

A PayPlug não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado, se o modo atual tem uma chave secreta (Test Secret Key no modo de teste, Live Secret Key no modo de produção), se a moeda da finalização de compra é EUR e se o total do pedido está entre 0,99 e 20.000,00 EUR. 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. Os desenvolvedores podem alterar as moedas e os limites pelos eventos do OpenCart ppg_supported_currencies e ppg_amount_limits (valores em centavos), e a requisição de pagamento pelo ppg_payment_data.

O pagamento foi feito, mas o pedido continua sem status: a notificação não chegou à sua loja e o cliente não voltou. Verifique se a sua loja está acessível pela internet na Notification URL mostrada nas configurações, por exemplo se nenhum firewall ou proteção por senha a bloqueia. Ative Logging e verifique o campo Log para ver notificações recusadas.

A notificação responde Verification failed.: o pagamento não pôde ser lido pela API da PayPlug, por exemplo porque a PayPlug não respondeu ou porque a chave secreta do modo do pagamento não está definida. O pedido não é alterado, e a PayPlug enviará a notificação novamente.

A notificação responde Temporarily unavailable.: o carrinho estava sendo atualizado por outra requisição naquele momento, por exemplo o retorno do cliente, ou o status do pedido não pôde ser definido. A PayPlug enviará a notificação novamente. O log mostra o motivo.

A notificação responde Unknown payment. ou Payment does not belong to the order.: o pagamento não foi criado por esta loja ou não é deste pedido, por exemplo um pagamento de outra loja na mesma conta da PayPlug. Ele é ignorado.

A URL de notificação mostra Method not allowed. no navegador: isso é normal. A URL aceita somente requisições da PayPlug.

O cliente vê um erro depois de Confirm Order: ative Logging e verifique o campo Log. Uma chave incorreta gera This payment method is temporarily unavailable. Please choose another payment method.; outras mensagens indicam o campo de cobrança que a PayPlug recusou.

O cliente volta e vê Payment verification failed.: o link de retorno não corresponde a nenhuma tentativa de pagamento do pedido, por exemplo porque foi aberto em outro navegador. Verifique o pagamento no portal da PayPlug; a notificação ainda define o status do pedido.

O pedido fica em espera após o pagamento: leia as observações na aba VibeFox PayPlug Gateway (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.

Não há formulário de reembolso na aba: a aba informa o motivo: o pagamento ainda não foi pago, foi totalmente reembolsado, o seu grupo de usuários não tem o direito de modificar a extensão, ou a chave secreta do modo do pagamento não está configurada.

O reembolso falha com Unexpected response from PayPlug.: a PayPlug respondeu sem um reembolso válido. Nada foi registrado. Verifique o reembolso no portal da PayPlug antes de tentar novamente.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox PayPlug Gateway. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações 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. O evento do OpenCart da extensão também é removido (no OpenCart 4, também os seus eventos e a sua ação de inicialização, que deixam passar a notificação e o retorno do cliente em modo de manutenção). Se Delete Data on Uninstall estiver ligado, as demais configurações (título, descrição, modo de teste, chaves secretas, log) e o log são excluídos. Se estiver desligado, elas são mantidas para uma reinstalação posterior. Os registros de pagamentos e reembolsos da PayPlug são sempre mantidos, por isso pedidos pagos antes podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas observações de pagamento.

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 PayPlug Gateway na lista de extensões instaladas e depois em Delete (o botão vermelho de lixeira) para remover o pacote enviado.

PayPlug é uma marca de seu respectivo titular. Esta extensão não é afiliada nem endossada pela PayPlug.