VibeFox PayU India for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 6.0 ou superior, instalado e ativo. O plugin não ativa sem ele; se o WooCommerce for desativado posteriormente, o plugin não faz nada e exibe um aviso na área administrativa.

PHP: 8.0 ou superior.

Store currency: Rúpia indiana (INR). A PayU India cobra exclusivamente em rúpias. Para outras moedas, o método de pagamento fica oculto na finalização de compra.

Phone number: A PayU exige um número de telefone para cada pagamento. Torne o campo de telefone obrigatório, ou ao menos visível, na sua finalização de compra.

PayU India account: você precisa do Merchant Key e do Merchant Salt (v1) de PayU Dashboard > Payment Gateway > Key Salt Details. Alterne o painel para o Test Mode para ver o par de testes. Use o Salt v1, não o Salt v2.

Internet access to your site: necessário para o webhook opcional. Sem ele, os pedidos são confirmados quando o cliente retorna da PayU.

VibeFox license key: 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_india_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > PayU India > 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 o Merchant Key e o Salt de teste, bem como o Merchant Key e o Salt de produção (veja Configuração).

6. Recomendado: em PayU Dashboard > Webhooks, adicione a URL do webhook mostrada na página de configurações para pagamentos bem-sucedidos e com falha.

7. Escolha o Mode e ative Enable/Disable. Teste um pagamento no modo Test e depois mude para Live.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > PayU India. Acima dos campos, a página avisa quando a chave ou o salt do modo atual estiver faltando, exibe Test mode is active: payments go to test.payu.in and no real money is charged. no modo Test e avisa quando a moeda da loja não for INR (nesse caso, o gateway fica oculto na finalização de compra).

Ao salvar, espaços e quebras de linha são removidos de chaves e salts, pois um salt com um espaço colado acidentalmente faria a verificação de todas as respostas da PayU falhar.

Geral

Enable/Disable: Enable PayU India Payment Gateway ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o título do método de pagamento que o cliente vê durante a finalização de compra. Padrão: PayU India.

Description: a descrição do método de pagamento que o cliente vê durante a finalização de compra. Padrão: Pay securely via Credit/Debit Card, NetBanking, UPI, or Wallets through PayU.

Credenciais de API

Copie o Merchant Key e o Merchant Salt (v1) de PayU Dashboard > Payment Gateway > Key Salt Details. Alterne o painel para o Test Mode para obter o par de teste.

Mode: qual ambiente da PayU os novos pagamentos utilizam.

Os reembolsos sempre vão para o modo em que o pagamento foi realizado.

Live Merchant Key: o seu Merchant Key de produção da PayU.

Live Merchant Salt (v1): o seu Merchant Salt (v1) de produção da PayU. Ele assina solicitações e verifica as respostas da PayU. Mantenha-o em segredo.

Test Merchant Key: o seu Merchant Key de teste da PayU, usado somente no modo Test.

Test Merchant Salt (v1): o seu Merchant Salt (v1) de teste da PayU, usado somente no modo Test.

Return and webhook URLs

Return URL: tem o formato https://your-site/wc-api/payu_p_callback/. É enviada à PayU automaticamente a cada pagamento; nada precisa ser configurado.

Webhook URL: tem o formato https://your-site/wc-api/payu_p_webhook/. Opcional, mas recomendada: confirma pagamentos mesmo se o cliente fechar o navegador antes de retornar à loja. Adicione-a em PayU Dashboard > Webhooks para pagamentos bem-sucedidos e com falha. Copie a URL exatamente como exibida na página de configurações.

Avançado

Verify Payment: Double-check every successful payment with the PayU verify_payment API. Recomendado. Se a checagem não puder ser concluída, o pedido é colocado em espera em vez de ser marcado como pago. Padrão: ativado.

Enable Logging: Log gateway events for troubleshooting. Gravado em WooCommerce > Status > Logs, origem wcp_payu_india_payment. Erros e avisos são sempre registrados; esta opção adiciona os demais eventos. Chaves, salts e dados pessoais dos clientes nunca são registrados. Padrão: desativado.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted (orders are never deleted). Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão PayU India) e faz o pedido. Se o pedido não tiver telefone de cobrança (ou de entrega), o cliente vê PayU India requires a phone number. Please enter your phone number and try again. Caso contrário, o cliente vai para uma página breve Thank you for your order. You will be redirected to PayU to complete your payment., que envia uma solicitação de pagamento assinada para a finalização de compra hospedada da PayU. Lá o cliente paga com cartão, NetBanking, UPI ou carteira digital.

Cada página de pagamento recebe seu próprio ID de transação da PayU, armazenado no pedido com o valor e o modo. Um pagamento feito em uma página de pagamento aberta anteriormente do mesmo pedido continua sendo aceito. Um pedido pago, em espera ou cancelado nunca recebe um novo formulário de pagamento, evitando que o botão Voltar do navegador inicie um segundo pagamento.

A PayU envia o resultado de volta com o cliente e, se configurado, por webhook. Um resultado só é aceito com um hash válido da PayU gerado com a chave e o salt do modo em que o pagamento foi iniciado, e apenas para um ID de transação emitido para aquele pedido. Com Verify Payment ativado, um resultado bem-sucedido também é verificado com a API verify_payment da PayU. O valor pago deve ser idêntico ao total do pedido até o último paisa, em INR. O pedido só é marcado como pago depois que a PayU confirma dessa forma. O plugin processa os seguintes resultados da PayU:

Após um pagamento bem-sucedido ou pendente, o cliente vê a página de pedido recebido. Após um pagamento malsucedido, o cliente retorna à finalização de compra com uma mensagem: Payment was not completed. Please try again or choose a different payment method., Payment was cancelled. You may try again. ou, quando o resultado não puder ser verificado, We could not confirm the payment result. If your account was charged, please contact us before paying again. As mensagens funcionam na finalização de compra clássica e no bloco de Finalizar compra.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalizar compra e na página Pay for order. É compatível com o armazenamento de pedidos de alto desempenho do WooCommerce (HPOS).

O plugin cobra exclusivamente em INR e não possui processamento multimoeda (MCP). Ele não oferece cartões salvos ou tokenização, nem WooCommerce Subscriptions, nem formulário de cartão no site (seamless), nem gerenciamento de parcelamento (EMI) ou ofertas, nem checkout em um clique da PayU.

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi enviado para a PayU e ainda não pagou.

Processing: o pagamento foi confirmado. A nota do pedido mostra o ID da transação da PayU (mihpayid), o modo de pagamento e o código do banco. O ID da transação do pedido é o mihpayid da PayU. Pedidos contendo apenas produtos virtuais para download tornam-se Concluído, como o WooCommerce faz por padrão.

On hold: o pagamento ainda está pendente na PayU (UPI ou NetBanking), o valor pago ou a moeda diferem do pedido, a API verify_payment não pôde ser acessada ou ainda não confirmou o pagamento, ou chegou um pagamento para um pedido que havia sido cancelado. A nota do pedido informa o motivo. Verifique a transação no PayU Dashboard e conclua-a ou reembolse-a. Quando a verificação falhar, o pedido será confirmado automaticamente na próxima entrega do resultado.

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

Se a PayU reportar outro pagamento bem-sucedido para um pedido que já está pago, uma nota solicitará que você reembolse a duplicata no PayU Dashboard.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via PayU India (o botão exibe o seu Title). São aceitos reembolsos totais e parciais; o valor deve ser maior que zero. O reembolso é enviado pela API de reembolsos da PayU com a chave e o salt do modo em que o pagamento foi realizado, de modo que essas credenciais devem estar configuradas. Se a PayU rejeitar o reembolso, o WooCommerce exibe a mensagem da PayU e nenhum reembolso é registrado.

A PayU enfileira os reembolsos e os processa de forma assíncrona; o cliente geralmente recebe o dinheiro em 5 a 7 dias úteis. A nota do pedido mostra o valor, o ID de solicitação da PayU e o motivo. O plugin não consulta o status do reembolso posteriormente.

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 India. 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 vaga do domínio. Libere a vaga na sua conta em vibefox.net.

Sem uma chave ativa, a PayU India 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. Gerentes da loja 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 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 necessitam de renovação. O status é verificado novamente de forma automática em segundo plano.

Solução de problemas

PayU India does not appear at checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se a chave e o salt do Mode selecionado estão preenchidos. Verifique se a moeda da loja (ou a moeda do pedido na página Pay for order) é INR. A página de configurações exibe um aviso para cada um desses problemas.

The payment went through, but the order stays Pending payment: o cliente não retornou à loja e nenhum webhook chegou. Adicione a URL do webhook das configurações em PayU Dashboard > Webhooks para pagamentos bem-sucedidos e com falha, e garanta que ela esteja acessível pela internet.

Webhook answers invalid_signature: o hash da PayU não coincidiu. Verifique se a chave e o salt do modo de pagamento estão corretos e se o Salt v1 está sendo usado, não o Salt v2. O pedido não é alterado.

Webhook answers not_configured: a chave ou o salt do modo em que o pagamento foi iniciado estão ausentes. Informe-os; a PayU tentará enviar o webhook novamente.

Webhook answers verify_unavailable: a API verify_payment ainda não conseguiu confirmar o pagamento. O pedido fica em espera e o próximo envio executará a verificação novamente.

The customer sees PayU India requires a phone number: torne o campo de telefone obrigatório ou visível na finalização de compra. É utilizado o telefone de cobrança, ou o de entrega quando apenas este estiver preenchido.

The order is On hold: leia a nota do pedido. O motivo é um pagamento pendente de UPI ou NetBanking, divergência de valor ou moeda, falha ou pendência na verificação, ou um pagamento referente a um pedido cancelado.

Refund fails: PayU transaction ID not found for this order. significa que o pedido não possui um pagamento da PayU. Uma mensagem informando que Merchant Key/Salt do modo do pagamento não estão definidos indica que você deve primeiro inserir as credenciais daquele modo.

Too little in the log: erros e avisos são sempre gravados; ative Enable Logging para ver também cada solicitação e resultado da PayU.

Developer hooks: o filtro payu_p_request_fields altera os campos da solicitação de pagamento antes de serem assinados; o filtro payu_p_icon altera o ícone da finalização de compra.

The license block shows an error: 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 foi alterado, 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 continuará 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 registros deste plugin (arquivos de log e linhas do registro de banco de dados do WooCommerce) são excluídos apenas se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Pedidos existentes mantêm suas notas de pagamento, IDs de transação da PayU e IDs de solicitação de reembolso.

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