VibeFox PayU for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele; se o WooCommerce for desativado posteriormente, o plugin não executa nenhuma ação e exibe um aviso na área administrativa.

PHP: 8.0 ou superior.

Moeda da loja: uma das opções PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. A moeda também deve estar habilitada para o seu ponto de venda na PayU. Para outras moedas, o método de pagamento fica oculto na finalização de compra.

Acesso da internet ao seu site: a PayU envia notificações de pagamento para a sua loja; portanto, o site deve estar acessível pela internet (não protegido por autenticação HTTP ou página de manutenção). Sem notificações, os pedidos ainda são verificados quando o cliente retorna da PayU.

Conta PayU: você precisa de quatro chaves do seu ponto de venda (POS): POS ID, Second key (MD5), client_id OAuth e client_secret OAuth. Elas estão no painel de comerciante da PayU em Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. As chaves de sandbox vêm de uma conta sandbox PayU separada.

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_payu_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > PayU > Manage, ou clique em Settings sob o 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 quatro chaves de Sandbox e as quatro chaves de Live (veja Configuração). Nenhuma URL de notificação precisa ser configurada na PayU.

6. Ative Enable/Disable. Deixe Test Mode ativado até fazer um pagamento de teste; depois, desmarque-o para aceitar pagamentos reais com as chaves de Live.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > PayU. Acima dos campos, a página avisa enquanto o modo sandbox estiver ativo, quando faltar uma das quatro chaves do modo atual ou quando a PayU não aceitar a moeda da loja. Nos dois últimos casos, a PayU não é exibida na finalização de compra.

Ao salvar, espaços e quebras de linha são removidos de todas as chaves, pois copiá-las do painel da PayU frequentemente os inclui.

Geral

Enable/Disable: Enable PayU payment gateway ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o título do método de pagamento exibido ao cliente. Padrão: PayU.

Description: a descrição do método de pagamento exibida ao cliente. Padrão: Pay securely via PayU.

Credenciais de API

Encontre as chaves no painel de comerciante da PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. As chaves de sandbox vêm de uma conta sandbox PayU separada. Todas as quatro chaves do modo devem ser preenchidas.

Test Mode: Enable sandbox (test) mode. Usa o sandbox da PayU e as chaves de Sandbox abaixo. Nenhum dinheiro real é cobrado. Na finalização de compra clássica e no bloco de Finalização de compra, o cliente vê Sandbox mode — no real money is charged. Desative-o para aceitar pagamentos reais com as chaves de Live. Padrão: ativado.

Live POS ID: o POS ID (merchantPosId) do seu ponto de venda de produção.

Live Second Key (MD5): usada para verificar a assinatura das notificações da PayU.

Live OAuth Client ID: o client_id OAuth do ponto de venda.

Live OAuth Client Secret: o client_secret OAuth do ponto de venda.

Sandbox POS ID: o POS ID do seu ponto de venda no sandbox da PayU.

Sandbox Second Key (MD5): usada para verificar a assinatura das notificações do sandbox da PayU.

Sandbox OAuth Client ID: o client_id OAuth do ponto de venda sandbox.

Sandbox OAuth Client Secret: o client_secret OAuth do ponto de venda sandbox.

Cada pagamento lembra o seu próprio ambiente. Notificações, verificações de status e reembolsos de um pagamento sempre usam as chaves desse ambiente, de modo que pagamentos anteriores continuam funcionando após uma troca. Uma notificação assinada com a chave sandbox nunca é aceita para um pagamento em produção.

Notificações de pagamento

Esta seção mostra a URL de notificação, com o formato https://your-site/wc-api/wc_pu_payment/. O plugin a envia à PayU a cada pagamento, portanto nada precisa ser configurado no painel da PayU. Certifique-se de que ela esteja acessível pela internet (não bloqueada por firewall, modo de manutenção ou autenticação HTTP).

Avançado

Receive payments automatically: Automatically receive payments waiting for confirmation. Isso só tem efeito se o recebimento automático estiver desativado para o seu POS no painel da PayU: os pagamentos aguardam confirmação (WAITING_FOR_CONFIRMATION). Quando essa opção está ativada, o plugin recebe esses pagamentos imediatamente. Quando desativada, esses pedidos são colocados em espera e você recebe ou cancela o pagamento pelas ações do pedido Receive PayU payment e Cancel PayU payment. Padrão: ativado.

Logging: Enable logging registra eventos técnicos (números de pedidos, IDs de pedidos PayU, status, erros; sem chaves ou dados pessoais) em WooCommerce > Status > Logs, origem wcp_payu_payment. Padrão: desativado.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. Pedidos e seus respectivos dados de pagamento nunca são excluídos. A desativação do plugin mantém tudo salvo. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão PayU) e faz o pedido. O plugin cria um pedido PayU com o valor total na moeda do pedido, com a descrição Order #, o número do pedido e o nome da sua loja, além dos itens do pedido, frete e taxas para exibição na página da PayU. O idioma da página da PayU acompanha o idioma da loja quando a PayU o suporta; caso contrário, em inglês. O cliente é direcionado à página de pagamento da PayU, escolhe um método lá e conclui o pagamento.

Cada tentativa de pagamento recebe o seu próprio pedido PayU. Quando o cliente tenta pagar novamente (após um pagamento com falha ou cancelado, ou a partir da página Pay for order), o pagamento PayU inacabado anterior do pedido é cancelado na PayU, impedindo que um link de pagamento antigo seja pago duas vezes.

O simples retorno à sua loja nunca dá um pedido como pago. O pedido só é marcado como pago após confirmação da PayU: por uma notificação assinada com a Second Key do ambiente do pagamento ou por uma verificação de status do pedido PayU no servidor no momento em que o cliente retorna (útil caso a notificação atrase). O pedido PayU deve ser o criado para esse pedido, e o valor e a moeda devem coincidir. O plugin processa estes status da PayU:

Na página de pedido recebido, enquanto o pedido ainda estiver no status Pagamento pendente, o cliente vê We have not received the payment confirmation from PayU yet. If the payment was interrupted, you can try again: ou, após um pagamento com falha, The payment was not completed. You can try again:, cada um com um botão Pay again. Para um pedido em espera, a mensagem é Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Se a PayU não conseguir iniciar o pagamento, o cliente vê Payment error. Please try again or choose another payment method. O motivo técnico (código HTTP e status da PayU) é registrado no log e em uma nota do pedido PayU payment could not be started:. Se faltarem as chaves do modo atual, a mensagem exibida é Payment gateway is not configured properly. Please contact the administrator.

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.

O cliente escolhe o método de pagamento na página da PayU, não na sua finalização de compra. O plugin não possui formulário de cartão na sua loja, não oferece cartões salvos ou pagamentos com um clique, não tem assinaturas e não possui widgets de parcelamento ou crédito da PayU. Ele utiliza um ponto de venda por ambiente (sem divisão de ponto de venda por moeda).

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi direcionado à PayU e ainda não pagou. A nota do pedido mostra o ID do pedido PayU e o ambiente (sandbox ou live).

Processing: o pagamento foi confirmado. A nota do pedido mostra o ID do pedido PayU, o valor e o ambiente. O ID da transação é o ID do pedido PayU que foi pago. Pedidos contendo apenas produtos virtuais para download tornam-se Concluídos, como o WooCommerce faz por padrão.

On hold: o valor ou a moeda pagos não coincidiam com o pedido, um pagamento foi concluído para um pedido que havia sido cancelado, ou um pagamento aguarda a sua confirmação (recebimento automático desativado ou falha no recebimento). A nota do pedido informa o caso e as providências a tomar.

Failed: o pagamento PayU mais recente foi cancelado ou recusado. O cliente pode tentar pagar novamente.

Cada notificação é processada uma única vez, sob um bloqueio por pedido: notificações repetidas não adicionam notas, não reduzem o estoque novamente e não enviam e-mails em duplicidade. Se outro pagamento for concluído para um pedido já pago ou reembolsado, uma nota solicita que você o reembolse no painel da PayU. Um pagamento aguardando confirmação em um pedido já pago ou finalizado é cancelado automaticamente, garantindo que o dinheiro não seja cobrado duas vezes.

Pagamentos aguardando confirmação

Para um pedido não pago com um pagamento aguardando confirmação, a tela do pedido disponibiliza duas ações de pedido: Receive PayU payment (waiting for confirmation) e Cancel PayU payment (release the funds). Escolha uma e clique no botão de atualização. A ação é registrada nas notas do pedido com o seu nome de usuário, e o novo status da PayU é aplicado imediatamente.

Reembolsos

Abra o pedido, clique em Refund, insira o valor e clique em Refund via PayU (o botão exibe o seu Title). São suportados reembolsos totais e parciais. O reembolso é enviado para o pedido PayU efetivamente pago, com as chaves do ambiente do pagamento; portanto, essas chaves devem estar configuradas. O motivo do reembolso é enviado como a descrição do reembolso. Se a PayU recusar o reembolso, o WooCommerce exibe o erro da PayU e nenhum reembolso é registrado.

Os reembolsos são assíncronos na PayU. O plugin adiciona imediatamente uma nota com o ID de reembolso PayU e o status; o status final chega depois em uma notificação da PayU e é inserido como nota. Se a PayU cancelar um reembolso, a nota informa que o dinheiro não foi devolvido ao cliente.

Pedidos colocados em espera devido a divergência de valor ou moeda mantêm o ID do pedido PayU como ID da transação, permitindo reembolsar o pagamento tanto pelo WooCommerce quanto no painel da PayU.

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 > PayU. 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 em vibefox.net.

Uma chave funciona em um domínio. Remover a chave de um site não libera a sua vaga de domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a PayU não é mostrada 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. Gerentes da loja logados continuam vendo 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 é exibido na página Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados e reembolsos funcionam normalmente.

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 PayU não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se todas as quatro chaves do modo atual estão preenchidas: as chaves de Sandbox no modo sandbox, as chaves de Live no modo live. Verifique se a moeda da loja (ou a moeda do pedido na página Pay for order) é uma das moedas suportadas. A página de configurações exibe um aviso para cada um desses problemas.

O pagamento foi concluído, mas o pedido continua como Pagamento pendente: a PayU ainda não entregou a notificação e a checagem de status na página de retorno não identificou um pagamento concluído. Verifique se a URL de notificação exibida nas configurações está acessível pela internet. Ative Logging para verificar o que está chegando.

A notificação responde Invalid signature: a notificação não foi assinada com a Second Key de nenhum dos ambientes. Verifique Live Second Key (MD5) e Sandbox Second Key (MD5). A resposta Invalid signature for this payment significa que a notificação foi assinada com a chave do ambiente oposto ao do pagamento.

A notificação responde Ignored: o pedido PayU não pertence a um pedido desta loja pago com a PayU, pertencendo por exemplo a outra loja no mesmo POS. A PayU interrompe novas tentativas.

O pagamento não é criado: ative Logging e consulte WooCommerce > Status > Logs, origem wcp_payu_payment. O registro mostra o código HTTP e o status da PayU. A mensagem Could not authenticate with PayU (check the OAuth client ID / secret). indica chaves OAuth incorretas no modo atual.

O pedido está Em espera: leia a nota do pedido. O motivo é uma divergência de valor ou moeda, um pagamento após cancelamento ou um pagamento aguardando confirmação. No último caso, utilize as ações do pedido Receive PayU payment ou Cancel PayU payment.

Falha no reembolso: This order has no completed PayU payment. Cannot process refund. significa que o pedido não possui um pedido PayU pago. A indicação de que as chaves de Sandbox ou Live estão faltando significa que o pagamento foi realizado naquele ambiente e suas chaves não foram preenchidas. Insira-as e tente novamente.

Outras moedas: desenvolvedores podem alterar a lista de moedas com o filtro wc_pu_supported_currencies e o ícone de finalização de compra com o filtro wc_pu_icon.

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 em 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 todas as configurações; apenas os tokens de acesso PayU em cache são descartados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos, juntamente com os tokens em cache. As configurações do gateway e o registro deste plugin são removidos apenas se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação futura. Pedidos existentes preservam suas notas de pagamento, IDs de pedidos PayU e IDs de transação.

A PayU é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela PayU.