VibeFox PayPlug for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Moeda e valores: euro (EUR), de 0,99 a 20.000,00 por pagamento, os padrões do PayPlug. Com outra moeda do carrinho ou fora desses limites, o método de pagamento fica oculto.
Conta no PayPlug: você precisa das chaves secretas da sua conta no 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 no PayPlug. Sua loja precisa estar acessível pela internet para receber notificações; caso contrário, os pedidos são criados quando o cliente retorna do PayPlug.
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 upload terminar, clique em Configure, ou encontre VibeFox PayPlug Gateway depois na lista de módulos e clique em Configure.
3. Cole 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. Cole as suas chaves secretas do portal do 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.
Na instalação, o módulo cria o status de pedido PayPlug payment on hold. O PrestaShop disponibiliza o novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox PayPlug Gateway > 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 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.
Finalização de compra
Enable/Disable: Enable PayPlug Gateway liga ou desliga o método de pagamento. Padrão: off.
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: PayPlug. Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely by card via PayPlug.
Chaves de API
Encontre as suas chaves secretas no portal do 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. Pagamentos feitos no outro modo continuam usando a chave do próprio modo para verificações de status e reembolsos. Padrão: on. Enquanto estiver ativado, os clientes veem Test mode: no real payment will be made. abaixo do método de pagamento.
Test Secret Key: a sua chave secreta de teste do PayPlug. Ela começa com sk_test_.
Live Secret Key: a sua chave secreta de produção do PayPlug. Ela começa com sk_live_.
Uma chave com o prefixo errado não é salva. A página mostra, por exemplo, Test Secret Key must start with "sk_test_". The previous value was kept. As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo.
Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Notification URL: o endereço que o módulo envia ao PayPlug com cada pagamento. Com URLs amigáveis, ele tem este formato: https://your-shop/module/wcp_payplug_gateway/webhook. Não é preciso informar nada no portal do PayPlug. A URL precisa estar acessível pela internet; caso contrário, os pedidos são criados quando o cliente retorna do PayPlug.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido imediatamente, sem uma segunda mudança de status.
Avançado
Logging: registra chamadas à API e notificações em logs/ppg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados. Chaves secretas, dados de cartão e dados de clientes nunca são registrados. Padrão: off.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ativado, as configurações do módulo e o seu log são excluídos ao desinstalar o módulo. Os IDs de pagamento do PayPlug salvos nos pedidos e o status de pedido PayPlug payment on hold são mantidos. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão PayPlug, com o logotipo do PayPlug). No modo de teste, a opção mostra Test mode: no real payment will be made. Após a confirmação, o módulo cria um pagamento no PayPlug pelo total do carrinho em centavos e envia o cliente à página de pagamento do PayPlug. Os endereços de cobrança e de entrega, o e-mail e o idioma do carrinho são transmitidos ao PayPlug. Lá o cliente paga com cartão. Nesse momento, ainda não existe nenhum pedido.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que o PayPlug confirma: o módulo lê o pagamento na API do PayPlug quando a notificação chega e quando o cliente volta. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with PayPlug has been received. Se o pedido estiver em espera, a página informa We are confirming your payment with PayPlug. The order will be updated automatically — please do not pay again. Se o pedido estiver em Payment error ou tiver sido cancelado sem pagamento, a página informa Your PayPlug payment was not completed. Please contact us about this order. Se não foi possível consultar o PayPlug quando o cliente voltou, uma página Payment confirmation mostra o mesmo texto de "we are confirming" e um botão Check again; a notificação cria o pedido assim que chegar.
Se o cliente cancelar na página do PayPlug, a página de pagamento é fechada no PayPlug, então ela não pode 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 ficou aberto, Your PayPlug payment was not completed. You can try again or choose another payment method. O carrinho é mantido.
Quando o cliente paga novamente o mesmo carrinho, o módulo primeiro verifica a tentativa anterior. Se ela tiver sido paga nesse meio tempo, o pedido é criado sem um novo pagamento. Se ainda estiver aberta pelo mesmo valor, a mesma página de pagamento é usada novamente. Caso contrário, a página antiga é fechada no PayPlug e um novo pagamento é criado.
Se o PayPlug não conseguir iniciar o pagamento, o cliente permanece na finalização de compra 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 funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
Os pagamentos são capturados imediatamente. O módulo não tem parcelamento Oney, cartões salvos de um clique, formulário de pagamento incorporado, assinaturas nem captura diferida.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado ao PayPlug e não pagou, ou o PayPlug ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted or Delivered: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o ID do pagamento do PayPlug (pay_...) como ID da transação, e uma nota mostra o pagamento do PayPlug e o seu modo.
PayPlug payment on hold: o valor pago ou a moeda diferem do carrinho (nota amount/currency mismatch, por exemplo, o carrinho foi alterado depois que o pagamento começou); ou um pagamento de teste foi feito enquanto a loja estava em modo de produção, então nenhum dinheiro foi recebido e nenhum pagamento é registrado; ou o pagamento chegou para um pedido que havia sido cancelado; ou um pagamento está autorizado, mas não capturado (capture-o no portal do PayPlug; o pedido é marcado como pago quando o PayPlug informa que foi pago). A nota explica o que verificar.
Payment error: um pagamento autorizado de um pedido em espera falhou ou foi cancelado.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se uma segunda tentativa de um carrinho já pago também for paga, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no portal do PayPlug. Um pedido pago, cancelado ou reembolsado nunca é reaberto por uma notificação posterior.
Bloco de pagamento do PayPlug
A página do pedido mostra um bloco PayPlug payment com o ID do pagamento no PayPlug, o status do pagamento, o valor pago e reembolsado, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as PayPlug notes do pedido.
Reembolsos
No bloco PayPlug payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via PayPlug. Confirme a pergunta Refund this amount through PayPlug? This cannot be undone. Reembolsos totais e parciais são aceitos. Você precisa ter permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são feitos até o valor que o 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 vai para o pagamento que de fato quitou o pedido, com a chave secreta do modo (teste ou produção) em que foi feito; por isso essa chave precisa estar configurada. Se o PayPlug não aceitar o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID do reembolso do PayPlug e o motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis somente depois que o PayPlug informa o pagamento como pago.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pelo PayPlug.
Reembolsos feitos no portal do PayPlug chegam por notificação e são adicionados às notas uma única vez. Eles não são contabilizados no bloco e não alteram o status do pedido nem as notas de crédito. Registre-os manualmente, se necessário.
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 PayPlug Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox PayPlug Gateway > Configure, 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 deles ficam a linha Product: presta-payment-payplug 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, o PayPlug não é exibido 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. A vitrine da loja não sabe que você está conectado ao 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: pagamentos já iniciados continuam sendo confirmados, e os reembolsos funcionam.
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. Nenhum cron job é necessário. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
O PayPlug não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, 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 do carrinho é EUR e se o total do carrinho está entre 0,99 e 20.000,00 EUR. 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. Os desenvolvedores podem alterar as moedas e os limites com os hooks actionWcpPayplugSupportedCurrencies e actionWcpPayplugAmountLimits (valores em centavos).
O pagamento foi feito, mas nenhum pedido foi criado: a notificação não chegou à sua loja e o cliente não voltou. Verifique se a sua loja está acessível pela internet no Notification URL mostrado nas configurações, por exemplo se nenhum firewall ou proteção por senha a bloqueia. Ative o Logging e veja o campo Log para notificações rejeitadas.
A notificação responde Verification failed.: o pagamento não pôde ser lido na API do PayPlug, por exemplo porque o PayPlug não respondeu ou porque a chave secreta do modo do pagamento não está definida. O pedido não é alterado, e o PayPlug envia a notificação novamente.
A notificação responde Temporarily unavailable.: o carrinho 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). O PayPlug envia 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 carrinho, por exemplo um pagamento de outra loja na mesma conta do PayPlug. Ele é ignorado.
A URL de notificação mostra Method not allowed. no navegador: isso é normal. A URL aceita apenas requisições do PayPlug.
O cliente vê um erro ao escolher o PayPlug: ative o Logging e veja o campo Log. Uma chave errada gera This payment method is temporarily unavailable. Please choose another payment method.; as outras mensagens indicam o campo de cobrança que o PayPlug recusou.
O pedido está em PayPlug payment on hold depois do pagamento: leia as notas no bloco PayPlug payment (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e a chave secreta desse modo não está configurada. Informe-a e tente novamente.
O reembolso falha com Unexpected response from PayPlug.: o PayPlug respondeu sem um reembolso válido. Nada foi registrado. Verifique o reembolso no portal do PayPlug antes de tentar novamente.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox PayPlug Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete Data on 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. Os registros de pagamentos e reembolsos do PayPlug e o status de pedido PayPlug payment on hold são sempre mantidos, para que pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento e IDs de transação.
O PayPlug é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo PayPlug.