VibeFox PayU India for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a instalar em versões anteriores do PHP.
Moeda: rúpia indiana (INR). A PayU India cobra somente em rúpias. Para carrinhos em outras moedas, o método de pagamento fica oculto na finalização de compra.
Número de telefone: a PayU exige um número de telefone em todos os pagamentos. Torne o campo de telefone do endereço obrigatório ou, pelo menos, visível na sua finalização de compra.
Conta PayU India: você precisa da Merchant Key e do Merchant Salt (v1) em PayU Dashboard > Payment Gateway > Key Salt Details. Mude o painel para o Test Mode para ver o par de teste. Use o Salt v1, não o Salt v2.
Acesso à Internet para a sua loja: necessário para o webhook opcional. Sem ele, os pedidos são confirmados quando o cliente retorna da PayU.
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 depois VibeFox PayU India Payment Gateway na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Insira o Test Merchant Key e Salt e o Live Merchant Key e Salt (veja Configuração).
5. Recomendado: em PayU Dashboard > Webhooks, adicione a URL do webhook exibida na página Configure para pagamentos bem-sucedidos e com falha.
6. Escolha o Mode, ative Enable/Disable e clique em Save. Teste um pagamento no modo de teste e depois mude para o modo de produção.
Na instalação, o módulo cria dois status de pedido: Awaiting PayU India payment e PayU India payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences; a moeda INR deve continuar permitida para o módulo.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa se a chave ou o salt do modo atual estiver faltando, mostra Test mode is active: payments go to test.payu.in and no real money is charged. no modo de teste e exibe um erro se a moeda padrão da sua 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 das chaves e dos salts, pois um salt com um espaço colado faria todas as respostas da PayU falharem na verificação.
PayU India
Enable/Disable: Enable PayU India Payment Gateway ativa ou desativa o método de pagamento. Padrão: desativado. Se você ativá-lo sem a chave e o salt do modo atual, a página avisará após salvar.
Title: o título 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: PayU India. Obrigatório.
Description: a descrição do método de pagamento que o cliente vê na 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) em PayU Dashboard > Payment Gateway > Key Salt Details. Mude o painel para o Test Mode para obter o par de teste. A seção tem um link Open the PayU Dashboard.
Mode: o ambiente da PayU que os novos pagamentos usam.
Os pagamentos já iniciados mantêm o modo em que foram iniciados: os resultados deles são verificados e os reembolsos são enviados com a chave e o salt desse modo, mesmo depois de você mudar o modo.
Live Merchant Key: sua Merchant Key de produção da PayU.
Live Merchant Salt (v1): seu Merchant Salt (v1) de produção da PayU. Ele assina as solicitações e verifica as respostas da PayU. Mantenha-o em segredo.
Test Merchant Key: sua Merchant Key de teste da PayU, usada somente no modo de teste.
Test Merchant Salt (v1): seu Merchant Salt (v1) de teste da PayU, usado somente no modo de teste.
Os salts salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Clear saved salts: marque um salt e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
URLs de retorno e de webhook
Return URL: tem o formato https://your-shop/module/wcp_payu_india_payment/return, possivelmente com um código de idioma, como /en/. Ela é enviada à PayU automaticamente em cada pagamento; não há nada a configurar.
Webhook URL: tem o formato https://your-shop/module/wcp_payu_india_payment/webhook, possivelmente com um código de idioma. Opcional, mas recomendado: confirma os pagamentos mesmo que o cliente feche o navegador antes de voltar. Adicione-a em PayU Dashboard > Webhooks para pagamentos bem-sucedidos e com falha. Copie a URL exatamente como a página Configure a mostra. Ela precisa estar acessível pela Internet (sem autenticação básica nem bloqueio de firewall). O modo de manutenção da loja e as restrições de país não a bloqueiam.
O webhook traz o mesmo resultado assinado do retorno do cliente. Webhooks sem um hash válido da PayU são rejeitados.
Avançado
Verify Payment: verifica novamente cada pagamento bem-sucedido com a API verify_payment da PayU. Recomendado. Se a verificação não puder ser concluída, o pedido é colocado em espera em vez de ser marcado como pago. Padrão: ativado.
Enable Logging: registra os eventos do gateway para solução de problemas em logs/payu_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados; esta opção acrescenta os demais eventos, como cada formulário de pagamento e cada resultado da PayU. Chaves, salts e dados pessoais dos clientes nunca são registrados. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: exclui as configurações e os registros do módulo quando ele é desinstalado. Pedidos e registros de transações da PayU nunca são excluídos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, PayU India) e confirma. Se nem o endereço de cobrança nem o de entrega tiverem um número de telefone fixo ou celular, o cliente permanece na finalização de compra com PayU India requires a phone number. Please enter your phone number and try again. Caso contrário, ele vê uma página curta com Thank you for your order. You will be redirected to PayU to complete your payment., que envia à página de pagamento hospedada da PayU uma solicitação de pagamento assinada pelo total do carrinho. Se o navegador não continuar sozinho, a página tem um botão Pay with PayU e o botão Back to checkout. Na página da PayU, o cliente paga com cartão, NetBanking, UPI ou carteira digital. Nenhum pedido existe ainda nesse momento.
Cada tentativa de pagamento recebe seu próprio ID de transação da PayU, que começa com o número do carrinho, e é salva com o valor e o modo. Um pagamento feito em uma página de pagamento antiga e ainda aberta do mesmo carrinho continua sendo aceito. Um carrinho que já tem pedido nunca recebe um novo formulário de pagamento, portanto o botão Voltar do navegador não consegue iniciar um segundo pagamento.
A PayU envia o resultado junto 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 somente para um ID de transação emitido para aquele carrinho. Com Verify Payment ativado, um resultado bem-sucedido também é verificado com a API verify_payment da PayU. O valor pago deve ser igual ao valor da tentativa e ao total do carrinho até o último paisa, em INR. O pedido só é marcado como pago depois que a PayU confirma dessa forma. O módulo trata estes resultados da PayU:
Após um pagamento bem-sucedido ou pendente, o cliente vê a página padrão de confirmação do pedido. Um pagamento pendente acrescenta Your PayU payment is pending. The order will be updated as soon as PayU confirms the result — there is no need to pay again.; um pedido em espera acrescenta Your payment is being reviewed. We will contact you if anything else is needed.; e um pedido em Payment error ou Canceled mostra Your PayU payment was not completed. Please contact us about this order.
Após um pagamento sem sucesso, o cliente volta à 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 pôde ser verificado, We could not confirm the payment result. If your account was charged, please contact us before paying again. Se o resultado ainda estiver em processamento quando o cliente voltar, aparece uma página com We are confirming your PayU payment. If you completed the payment, your order will be created shortly — please do not pay again. e um botão Check again.
O módulo cobra exclusivamente em INR e não possui processamento multimoeda (MCP). Não oferece cartões salvos ou tokenização, nem assinaturas, nem formulário de cartão no site (seamless), nem gestão de parcelamento (EMI) ou ofertas, nem checkout em um clique da PayU.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à PayU e não pagou, ou o pagamento falhou ou foi cancelado. Existe apenas o carrinho.
Payment accepted: o pagamento foi confirmado. O pagamento é registrado com o ID de transação da PayU (mihpayid) como ID de transação, e uma nota mostra PayU payment successful. Transaction ID: …, Mode: …, Bank: …
Awaiting PayU India payment: um pagamento por UPI ou NetBanking ainda está pendente na PayU. O pedido passa para Payment accepted quando a PayU o confirma.
PayU India payment on hold: o valor ou a moeda pagos diferem do carrinho, 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 informa o motivo. Verifique a transação no PayU Dashboard e depois coloque o pedido em Payment accepted ou cancele-o e reembolse o pagamento. Quando somente a verificação falhou, o pedido é pago automaticamente na próxima entrega do resultado.
Payment error: um pagamento pendente foi recusado ou cancelado depois. Um resultado bem-sucedido posterior ainda paga o pedido.
Refunded: tudo o que foi pago foi reembolsado pelo módulo.
Se a PayU informar outro pagamento bem-sucedido para um pedido que já está pago, o pedido não é alterado e uma nota pede que você reembolse a duplicata no PayU Dashboard. Um pagamento da PayU para um carrinho que foi pedido com outro método de pagamento recebe uma nota e não paga esse pedido.
Bloco de pagamento PayU India
A página do pedido mostra um bloco PayU India payment com o ID de transação da PayU (mihpayid), o ID de transação da loja (txnid), o ambiente, o status na PayU, o modo e o banco do pagamento, o valor pago e o valor dos reembolsos solicitados, um selo Test mode para pagamentos de teste, o histórico de reembolsos e as notas do módulo. Para um pedido em espera, mostra um lembrete para revisar o pagamento.
Reembolsos
No bloco PayU India payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via PayU. Confirme a pergunta Refund this amount through PayU? This cannot be undone. Reembolsos totais e parciais são aceitos; o valor deve ser maior que zero e não exceder o restante do que a PayU cobrou. Você precisa ter permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. O reembolso é enviado pela API de reembolso da PayU com a chave e o salt do modo em que o pagamento foi feito, por isso essas credenciais precisam estar preenchidas. Se a PayU recusar o reembolso, o bloco mostra PayU refund failed: com a mensagem da PayU, e nenhum reembolso é registrado.
A PayU coloca os reembolsos em fila e os conclui de forma assíncrona; o cliente normalmente recebe o dinheiro em 5–7 dias úteis. O histórico de reembolsos e as notas mostram o valor, o ID da solicitação na PayU e o motivo. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a PayU informa o ID de transação do pagamento. O módulo não verifica o status do reembolso depois e não cria notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pela PayU.
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 PayU India Payment Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox PayU India Payment Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-payu-india 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 do 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 de alterar o endereço da loja, ou depois de 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, a PayU India não é exibida aos clientes na finalização de compra. Se mesmo assim um pagamento for iniciado, 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 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: os 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 inserção da chave, depois uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A PayU India não aparece na finalização de compra: 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 do carrinho é INR e se o módulo está permitido para essa moeda, para o país do cliente e para o grupo dele em Payment > Preferences. A página Configure mostra um aviso para credenciais ausentes e para uma moeda da loja diferente de INR.
O pagamento foi feito, mas nenhum pedido foi criado: o cliente não voltou à loja e nenhum webhook chegou. Adicione a URL do webhook da página Configure em PayU Dashboard > Webhooks para pagamentos bem-sucedidos e com falha, e certifique-se de que ela está acessível pela Internet.
O webhook responde invalid_signature: o hash da PayU não confere. Verifique se a chave e o salt do modo do pagamento estão corretos e se o Salt v1 está sendo usado, não o Salt v2. Um resultado de pagamento de produção assinado com o salt de teste, ou o contrário, também é rejeitado. Nada é alterado.
O webhook responde not_configured: a chave ou o salt do modo em que o pagamento foi iniciado está faltando. Insira-os; a PayU tenta o webhook novamente.
O webhook responde verify_unavailable: a API verify_payment ainda não conseguiu confirmar o pagamento. O pedido fica em espera, e a próxima entrega verifica novamente.
O webhook responde busy ou retry: o retorno do cliente do mesmo carrinho estava sendo processado no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A PayU tenta o webhook novamente. O motivo é gravado no registro.
O webhook responde ignored_unknown_txnid: a transação não foi iniciada por esta loja, por exemplo por outra loja que usa a mesma conta PayU. Nada é alterado.
O cliente vê PayU India requires a phone number: torne o campo de telefone do endereço obrigatório ou visível na finalização de compra. O endereço de cobrança é usado primeiro, depois o de entrega.
O pedido está em PayU India payment on hold: leia as notas no bloco PayU India payment. O motivo é uma diferença de valor ou de moeda, uma verificação com falha ou pendente, ou um pagamento para um pedido cancelado.
O reembolso falha: PayU transaction ID not found for this order. significa que o pedido ainda não tem um pagamento na PayU. This payment was made in Test mode, but the Merchant Key/Salt of that mode are not set. (ou Live mode) significa que você precisa inserir primeiro as credenciais desse modo. Invalid refund amount: at most … INR can be refunded. significa que o valor é maior que o restante do pagamento.
Pouca informação no registro: erros e avisos são sempre gravados; ative Enable Logging para ver também cada formulário de pagamento e cada resultado da PayU.
Hook para desenvolvedores: actionPayuPRequestFields altera os campos da solicitação de pagamento antes de serem assinados. Chave, ID de transação, valor e URLs de retorno não podem ser alterados por ele.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox PayU India Payment 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 registro são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de transações da PayU, as solicitações de reembolso e os status de pedido Awaiting PayU India payment e PayU India 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 suas notas de pagamento e os IDs de transação da PayU.
PayU é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à PayU nem endossado pela PayU.