VibeFox PayPlug for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Moeda e valores: euro (EUR), de 0,99 a 20.000,00 por pagamento, os padrões do PayPlug. Com outra moeda ou fora desses limites, o método de pagamento fica oculto.
Conta PayPlug: você precisa das chaves secretas da sua conta PayPlug: a chave de teste (sk_test_...) e/ou a chave de produção (sk_live_...). Nenhuma outra chave é necessária, e não é preciso configurar nenhuma notificação no PayPlug. Seu site precisa estar acessível pela internet para receber notificações; caso contrário, os pedidos são atualizados quando o cliente volta do PayPlug.
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_payplug_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > PayPlug > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Cole as chaves secretas do portal do PayPlug (veja Configuração).
6. Ative Enable/Disable e salve. Teste um pagamento com Test Mode ativado e depois desative-o para aceitar pagamentos reais.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > PayPlug. 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 da loja não é EUR. Nos dois casos, o método de pagamento fica oculto na finalização de compra. Na lista de métodos de pagamento, o PayPlug exibe um selo de modo de teste no modo de teste e aparece como pendente de configuração até que o modo atual tenha uma chave secreta.
Finalização de compra
Enable/Disable: Enable PayPlug Gateway ativa ou desativa o método de pagamento. Padrão: off.
Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: PayPlug.
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 suas chaves secretas no portal do PayPlug, em Developers > API keys. A seção também mostra a URL de notificação que o plugin envia com cada pagamento. Ela tem este formato: https://your-site/wc-api/ppg_payplug_webhook/. Não é preciso configurar nenhuma notificação no PayPlug.
Test Mode: Enable 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.
Test Secret Key: sua chave secreta de teste do PayPlug. Ela começa com sk_test_.
Live Secret Key: sua chave secreta de produção do PayPlug. Ela começa com sk_live_.
Uma chave com prefixo errado não é salva. A página mostra, por exemplo, A Test Secret Key deve começar com "sk_test_". O valor anterior foi mantido.
Pedidos
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido de imediato, sem uma segunda mudança de status.
Avançado
Logging: Enable debug logging registra chamadas à API e notificações em WooCommerce > Status > Logs, origem wcp_payplug_gateway. Erros são sempre registrados. Chaves secretas, dados de cartão e dados de clientes nunca são registrados. Padrão: off.
Delete Data on Uninstall: Remove all plugin data when uninstalling. Quando marcada, as configurações do plugin e os seus logs são excluídos ao apagar o plugin. Os IDs de pagamento do PayPlug salvos nos pedidos são mantidos. Padrão: off.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, PayPlug) e faz o pedido. No modo de teste, a finalização de compra mostra Modo de teste: nenhum pagamento real será feito. O plugin cria um pagamento no PayPlug pelo total do pedido em centavos e envia o cliente à página de pagamento do PayPlug. Os dados de cobrança e de entrega do pedido e o idioma do seu site são transmitidos ao 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 o PayPlug confirma: o plugin lê o pagamento na API do PayPlug quando a notificação chega e quando o cliente retorna. Um pagamento concluído leva o cliente à página de pedido recebido.
Se o cliente cancelar na página do PayPlug, a página de pagamento é fechada no PayPlug, para que não possa ser paga depois por engano. O cliente volta à página Pay for order com uma mensagem, por exemplo Você cancelou o pagamento do PayPlug. Você pode tentar novamente ou escolher outro método de pagamento., A sessão de pagamento do PayPlug expirou. Tente novamente ou escolha outro método de pagamento. ou O pagamento do PayPlug falhou. Tente novamente ou escolha outro método de pagamento.
Quando o cliente paga o mesmo pedido de novo, o plugin verifica primeiro a tentativa anterior. Se ela tiver sido paga nesse meio-tempo, o pedido é concluído sem um novo pagamento. Se ainda estiver aberta pelo mesmo valor, a mesma página de pagamento é reutilizada. 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 vê uma mensagem curta, por exemplo O PayPlug não pôde aceitar seus dados de cobrança (CEP). Verifique-os e tente novamente. ou Não foi possível contatar o provedor de pagamento. Tente novamente em instantes. O motivo técnico é adicionado às notas do pedido.
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. É compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
Os pagamentos são capturados imediatamente. O plugin não tem parcelamento Oney, Bancontact, Apple Pay ou American Express, cartões salvos de um clique, formulário de pagamento incorporado, assinaturas nem captura diferida.
Pedidos e reembolsos
Order statuses
Pending payment: o cliente foi enviado ao PayPlug e ainda não pagou, ou o PayPlug ainda não confirmou o pagamento.
Processing or Completed: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o pagamento do PayPlug e o seu modo. O ID da transação é o ID do pagamento no PayPlug (pay_...).
On hold: o valor ou a moeda pagos diferem do pedido (nota amount/currency mismatch); ou um pagamento de teste foi feito enquanto a loja está em modo de produção, então nenhum dinheiro foi recebido; 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 do pedido explica o que verificar.
Failed: a última tentativa de pagamento de um pedido pendente falhou ou foi cancelada. A falha de uma tentativa mais antiga não altera o pedido. O cliente pode pagar novamente.
Se uma segunda tentativa de um pedido que já está pago também for paga, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado no portal do PayPlug.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via PayPlug. Reembolsos totais e parciais são suportados. 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 WooCommerce exibe o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID de reembolso do PayPlug.
Reembolsos feitos no portal do PayPlug chegam por notificação e são adicionados às notas do pedido. Eles não são criados automaticamente no WooCommerce. Registre-os manualmente, se necessário.
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 > PayPlug. 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 novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em 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 em vibefox.net.
Sem uma chave ativa, o PayPlug não aparece para os 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 conectados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que possam 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: pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente, automaticamente, em segundo plano.
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á 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 loja é EUR e se o total do pedido está entre 0,99 e 20.000,00 EUR. Contas com outros limites podem alterá-los com o filtro ppg_amount_limits (valores em centavos).
O pagamento foi feito, mas o pedido continua em Pagamento pendente: a notificação não chegou à sua loja e o cliente não voltou. Verifique se o seu site está acessível pela internet na URL de notificação exibida nas configurações, por exemplo se algum modo de manutenção, firewall ou proteção por senha o bloqueia. Veja em WooCommerce > Status > Logs, origem wcp_payplug_gateway, as notificações recusadas.
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. O pedido não muda, e o PayPlug enviará a notificação novamente.
A notificação responde Busy, retry: o pedido estava sendo atualizado por outra requisição no mesmo momento, por exemplo o retorno do cliente. O PayPlug enviará a notificação novamente.
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 do PayPlug. Ele é ignorado.
O cliente vê Payment could not be initiated: a tentativa de pagamento anterior do pedido está sendo confirmada neste momento, ou o PayPlug recusou a solicitação. Aguarde um instante e tente novamente; as notas do pedido mostram o erro do PayPlug.
O pedido está em Aguardando após o pagamento: leia a nota do pedido. O valor ou a moeda pagos não correspondiam ao pedido, um pagamento de teste foi feito com a loja em produção, ou o pagamento chegou depois que o pedido foi cancelado. 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. Insira-a e tente novamente.
O bloco de licença exibe 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 em 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 Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e IDs de pagamento do PayPlug.
PayPlug é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pelo PayPlug.