VibeFox Przelewy24 for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Moeda: o pedido precisa estar em PLN, EUR, GBP ou CZK. Em outras moedas, o método de pagamento fica oculto na finalização de compra. O pedido é cobrado na sua própria moeda; o plugin não converte moedas.
Conta na Przelewy24: você precisa de uma conta de comerciante na Przelewy24 e dos seus dados de API: o Merchant ID, a chave de API (chamada report key no painel da Przelewy24), a chave CRC e, se a sua loja tiver um ID próprio, o POS ID (Shop ID). Você os encontra no painel de comerciante da Przelewy24, em panel.przelewy24.pl, em My data > API data and configuration. As chaves de sandbox vêm de uma conta sandbox separada, em sandbox.przelewy24.pl/panel. Não há mais nada a configurar no painel da Przelewy24: o plugin envia a sua URL de notificação com cada pagamento. O seu site precisa estar acessível pela internet, porque a Przelewy24 envia as notificações de pagamento para ele.
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_przelewy24_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Przelewy24 > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira as chaves de sandbox (Merchant ID, API key, CRC key; o POS ID somente se for diferente do Merchant ID), ative Enable/Disable, salve e faça um pagamento de teste no modo sandbox.
6. Insira as chaves de produção, desmarque Test Mode e salve para aceitar pagamentos reais.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Przelewy24. Acima dos campos, a página mostra avisos quando algo está faltando. Enquanto o sandbox estiver ativado: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. Quando as chaves do modo atual estão incompletas: Enter the Sandbox Merchant ID, API key and CRC key — until then Przelewy24 is not shown at checkout. (ou o mesmo para as chaves de produção). Quando a Przelewy24 não aceita a moeda da loja, o aviso informa a moeda e as moedas aceitas. Depois de salvar, os avisos acompanham imediatamente o novo modo e as novas chaves. Espaços e quebras de linha copiados junto com as chaves do painel da Przelewy24 são removidos ao salvar.
Finalização de compra
Enable/Disable: Enable Przelewy24 Payment 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. Padrão: Przelewy24.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with BLIK, online bank transfer or card via Przelewy24.
Credenciais de API
A seção explica onde encontrar as chaves (My data > API data and configuration no painel de comerciante da Przelewy24) e traz links para panel.przelewy24.pl e sandbox.przelewy24.pl/panel.
Test Mode: Enable sandbox (test) mode. Quando ativado, os novos pagamentos vão para o sandbox da Przelewy24 (sandbox.przelewy24.pl) com as chaves de sandbox, e nenhum dinheiro real é cobrado. Desmarque para aceitar pagamentos reais em secure.przelewy24.pl com as chaves de produção. Padrão: ativado.
Chaves de produção
Live Merchant ID: o seu ID de comerciante na Przelewy24, somente números.
Live POS ID (optional): o Shop ID (posId). Deixe em branco se for igual ao Merchant ID.
Live API key (report key): a chave de API do painel da Przelewy24. Ela é usada na autenticação da API, junto com o POS ID.
Live CRC key: usada para assinar as requisições enviadas à Przelewy24 e para verificar a assinatura das notificações da Przelewy24.
Chaves de sandbox
Sandbox Merchant ID: o Merchant ID da sua conta sandbox na Przelewy24.
Sandbox POS ID (optional): o Shop ID (posId) da conta sandbox. Deixe em branco se for igual ao Merchant ID.
Sandbox API key (report key): a chave de API da conta sandbox.
Sandbox CRC key: a chave CRC da conta sandbox, usada para assinar as requisições e verificar as notificações do sandbox.
As chaves de produção e de sandbox são diferentes. O Merchant ID e o POS ID devem conter somente dígitos; até que o Merchant ID, a API key e a CRC key do modo atual sejam inseridos, o método de pagamento não aparece na finalização de compra. Um pagamento iniciado em um modo é sempre verificado e reembolsado com as chaves desse modo, mesmo depois da troca; por isso, mantenha as chaves do modo antigo enquanto os pagamentos dele ainda estiverem abertos ou puderem ser reembolsados.
Notificações de pagamento
Esta seção mostra a URL de notificação da sua loja. Ela tem este formato: https://your-site/wc-api/wc_p24_payment/. O plugin envia essa URL à Przelewy24 em cada pagamento, então não é preciso configurar nada no painel da Przelewy24. A mesma URL recebe os resultados dos reembolsos. A URL precisa estar acessível pela internet: sem firewall, modo de manutenção ou autenticação HTTP à frente. Sem as notificações, o pagamento ainda é confirmado quando o cliente volta à página de pedido recebido (veja Finalização de compra); se o cliente não voltar, o pedido permanece em «Aguardando pagamento».
Avançado
Debug Log: Enable logging grava eventos técnicos (números de pedido, IDs de transação P24, erros) em WooCommerce > Status > Logs, origem wcp_przelewy24_payment. Erros e avisos são sempre registrados. Chaves, corpos de requisições e dados pessoais nunca são registrados. Padrão: desativado.
Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Pedidos e seus dados de pagamento nunca são excluídos. Desativar o plugin mantém tudo. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Przelewy24, com o logo P24 no bloco de Finalização de compra) e faz o pedido. No modo sandbox, o bloco de Finalização de compra mostra Sandbox mode — no real money is charged. O plugin registra uma transação na Przelewy24 pelo total do pedido na moeda do pedido, com o e-mail, o nome e o país de cobrança do cliente, e adiciona uma nota ao pedido com o ID de sessão e o modo (sandbox ou produção). Cada tentativa de pagamento recebe seu próprio ID de sessão. O cliente é enviado à página de pagamento da Przelewy24 e paga com BLIK, transferência bancária online, cartão ou outro método habilitado para a sua conta na Przelewy24. A página de pagamento é exibida no idioma do site, se a Przelewy24 o suportar; caso contrário, em inglês.
O pedido só é marcado como pago depois que a Przelewy24 confirma. A Przelewy24 envia uma notificação assinada para a sua loja. O plugin verifica a assinatura com a chave CRC, o Merchant ID e o POS ID; se a sessão foi registrada para este pedido e no mesmo modo; e se o valor e a moeda correspondem à tentativa de pagamento e ao total atual do pedido. Só então verifica a transação com a Przelewy24 (a Przelewy24 só credita pagamentos verificados) e marca o pedido como pago. Webhooks sem assinatura válida são rejeitados.
Depois de pagar, o cliente volta à página de pedido recebido. Se a notificação ainda não tiver chegado, o plugin pede à Przelewy24 o status da transação em uma requisição autenticada de servidor para servidor (no máximo uma vez a cada 10 segundos por pedido) e aplica as mesmas verificações. A página de retorno, sozinha, nunca marca um pedido como pago. Enquanto o pagamento não for confirmado, a página mostra We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: com um botão Pay again que abre a página Pay for order. Se o pedido estiver em espera, a página mostra Your payment is being verified. We will send you an e-mail as soon as it is confirmed. Um pagamento feito depois, em uma página antiga da Przelewy24 do mesmo pedido, continua sendo aceito.
Se o pagamento não puder ser iniciado, o cliente vê uma mensagem curta: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (o motivo vai para o log), Payment gateway is not configured properly. Please contact the administrator. (faltam as chaves do modo atual), uma mensagem informando que a Przelewy24 não pode aceitar pagamentos na moeda do pedido, ou The order total must be greater than zero. Um pedido já pago ou em espera não é enviado de novo à Przelewy24 (This order does not need a payment any more.).
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 WooCommerce High-Performance Order Storage (HPOS).
O plugin não oferece cartões salvos nem pagamentos com um clique, assinaturas ou pagamentos recorrentes, escolha do método de pagamento P24 (por exemplo, um campo de código BLIK) na página de finalização de compra, widgets de parcelamento, e não envia o conteúdo do carrinho à Przelewy24.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Przelewy24 e ainda não pagou, ou o pagamento ainda não foi confirmado.
Processing or Completed: o pagamento foi verificado. O WooCommerce define «Processando» ou «Concluído» (para pedidos com apenas produtos virtuais para download). A nota do pedido mostra o ID do pedido P24, o valor e o modo. O ID de transação do pedido é o ID do pedido P24. Cada pagamento é aplicado uma única vez.
On hold: o valor ou a moeda informados pela Przelewy24 diferem do pedido (por exemplo, o total do pedido foi alterado depois que o pagamento foi iniciado); o pagamento não foi confirmado e a nota informa isso. Ou o pagamento chegou e foi verificado para um pedido que havia sido cancelado; o pedido não é reaberto silenciosamente, e a nota pede que você envie o pedido ou reembolse o pagamento. Verifique o pagamento no painel da Przelewy24.
Se chegar um segundo pagamento para um pedido que já está pago ou reembolsado (um link de pagamento antigo, duas abas do navegador), ele não é confirmado, e a Przelewy24 não o credita. Uma nota no pedido pede que você o verifique no painel da Przelewy24 e, se necessário, o devolva ao comprador.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Przelewy24. Reembolsos totais e parciais são aceitos. O reembolso é enviado no modo em que o pagamento foi feito (sandbox ou produção), por isso as chaves desse modo precisam estar configuradas. A Przelewy24 processa os reembolsos de forma assíncrona: a nota do pedido primeiro informa que o reembolso foi solicitado, e o resultado chega depois na URL de notificação e é adicionado como nota: Przelewy24: refund of … completed. ou uma nota informando que o reembolso foi recusado e o dinheiro não foi devolvido. Se um reembolso for recusado, verifique-o no painel da Przelewy24; o reembolso do WooCommerce já registrado no pedido não é removido automaticamente.
Se a Przelewy24 não aceitar a solicitação de reembolso, o WooCommerce mostra Przelewy24 refund failed: com o motivo, e nenhum reembolso é registrado. Reembolsos feitos diretamente no painel da Przelewy24 não são adicionados ao pedido.
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 > Przelewy24. 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 a sua conta na vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera a vaga de domínio. Libere a vaga na sua conta na vibefox.net.
Sem uma chave ativa, a Przelewy24 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. Os gerentes da loja que estiverem logados ainda veem o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página de Plugins e nas páginas do WooCommerce. 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 de forma automática em segundo plano.
Solução de problemas
A Przelewy24 não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado, se o Merchant ID, a API key e a CRC key do modo atual estão preenchidos (as chaves de sandbox enquanto Test Mode estiver ativado, caso contrário as chaves de produção; Merchant ID e POS ID somente com dígitos) e se a moeda do pedido é PLN, EUR, GBP ou CZK. Os avisos no topo das configurações indicam o problema. Desenvolvedores podem alterar a lista de moedas com o filtro wc_p24_supported_currencies (somente moedas com duas casas decimais habilitadas na sua conta da Przelewy24).
O pagamento foi aprovado, mas o pedido continua em Pending payment: a notificação da Przelewy24 não chegou à sua loja e o cliente não voltou à página de pedido recebido. Verifique se a URL exibida em Payment notifications está acessível pela internet (sem modo de manutenção, firewall ou autenticação HTTP na frente de /wc-api/wc_p24_payment/) e se o Merchant ID, o POS ID e a CRC key do modo do pagamento estão corretos. As notificações rejeitadas são registradas em WooCommerce > Status > Logs, origem wcp_przelewy24_payment, mesmo com Debug Log desativado.
Como a loja responde às notificações: uma notificação processada, repetida ou desconhecida recebe resposta HTTP 200. Caso contrário, a Przelewy24 a reenvia mais tarde: 400 (dados ausentes ou malformados), 401 Invalid signature (chave CRC errada, outro Merchant ID ou POS ID, ou notificação assinada com as chaves do outro modo em relação ao pagamento), 405 (não é uma requisição POST), 500 Verification failed (a verificação com a Przelewy24 falhou; uma nota é adicionada ao pedido uma única vez) e 503 Busy, retry later (o pedido estava sendo atualizado por outra requisição no mesmo momento).
O cliente vê Payment error: Przelewy24 could not start the payment: a Przelewy24 recusou a transação, geralmente por chaves erradas do modo atual (as chaves de sandbox funcionam apenas no modo sandbox, e as de produção apenas no modo de produção). O erro da Przelewy24 está no log.
O pedido fica On hold após o pagamento: leia a nota do pedido. O valor ou a moeda não correspondiam ao pedido, ou o pagamento chegou para um pedido que havia sido cancelado. Verifique o pagamento no painel da Przelewy24 e, então, processe o pedido ou reembolse o pagamento.
Um reembolso falha: This order has no verified Przelewy24 payment. Cannot process refund. significa que o pedido não foi pago por meio de um pagamento verificado da Przelewy24. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (ou o mesmo para produção) significa que as chaves do modo do pagamento foram removidas; insira-as novamente.
O bloco de licença mostra 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 na vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave para o 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 e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin, assim como as marcações temporárias da página de retorno, são sempre removidos. As configurações do plugin e os seus logs (arquivos de log, inclusive os rotacionados, e as entradas de log no banco de dados da origem wcp_przelewy24_payment) são removidos somente se Delete data on uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes mantêm suas notas de pagamento, IDs de transação e dados de pagamento da Przelewy24.
A Przelewy24 é uma marca registrada de seu respectivo titular. Este plugin não é afiliado à Przelewy24 nem endossado por ela.