VibeFox PayU for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Moeda: uma de PLN, EUR, CZK, HUF, RON, BGN, GBP, USD, CHF, DKK, NOK, SEK, UAH. A moeda também deve estar ativada para o seu ponto de venda na PayU. Para outras moedas, a opção de pagamento fica oculta na finalização de compra.
Acesso à internet para a sua loja: a PayU envia notificações de pagamento para a sua loja, então ela precisa estar acessível pela internet (não atrás de autenticação HTTP ou firewall). Sem notificações, os pagamentos 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), OAuth client_id e OAuth client_secret. Elas estão no painel do lojista da PayU em Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. As chaves do 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 back office, acesse Modules > Module Manager e clique em Upload a module. Escolha o arquivo ZIP do módulo.
2. Quando o envio terminar, clique em Configure, ou encontre VibeFox PayU Payment na lista de módulos depois e clique em Configure.
3. Insira a 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 as quatro chaves Sandbox e as quatro chaves Live (veja Configuração). Não é preciso configurar nenhuma URL de notificação na PayU.
5. Ative Enable/Disable e clique em Save. Mantenha Test Mode ativado até fazer um pagamento de teste e depois desative-o para aceitar pagamentos reais com as chaves Live.
Ao instalar, o módulo cria dois status de pedido: Awaiting PayU payment confirmation e PayU payment on hold. O PrestaShop disponibiliza um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox PayU Payment > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página avisa enquanto o modo sandbox estiver ativado (O modo sandbox (teste) está ativado: os pagamentos vão para o sandbox da PayU e nenhum dinheiro real é cobrado. Não envie pedidos pagos no modo de teste.), quando uma das quatro chaves do modo atual está faltando e quando a PayU não aceita a moeda padrão 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 ao copiá-las do painel da PayU eles costumam ser adicionados. Um Title vazio não é salvo: a página mostra Insira um título para o método de pagamento.
PayU
Enable/Disable: Enable PayU payment gateway ativa ou desativa a opção de pagamento. Padrão: desativado.
Title: o título do método de pagamento exibido ao cliente. Também é o nome do método de pagamento salvo no pedido. Padrão: PayU. Obrigatório.
Description: a descrição do método de pagamento exibida ao cliente na finalização de compra. Padrão: Pay securely via PayU.
Credenciais de API
Encontre as chaves no painel do lojista da PayU: Online payments > My shops > your shop > Points of sale (POS) > your POS > Configuration keys. As chaves do sandbox vêm de uma conta sandbox PayU separada. Todas as quatro chaves de um modo devem estar preenchidas.
Test Mode: usa o sandbox da PayU e as chaves Sandbox abaixo. Nenhum dinheiro real é cobrado. Enquanto estiver ativado, os clientes veem Modo sandbox: nenhum pagamento real é realizado. abaixo da opção de pagamento. Desative-o para aceitar pagamentos reais com as chaves 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 no sandbox.
Sandbox OAuth Client Secret: o client_secret OAuth do ponto de venda no sandbox.
As Second Keys e os client secrets salvos nunca mais são exibidos. O campo fica vazio e mostra Salvo — deixe vazio para mantê-lo. Digite um novo valor apenas para alterá-lo. Os POS IDs e client IDs são exibidos como salvos.
Clear saved secrets: marque um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Cada pagamento guarda o seu ambiente. Notificações, verificações de status e reembolsos de um pagamento sempre usam as chaves desse ambiente, então os pagamentos anteriores continuam funcionando após você trocar de modo. Uma notificação assinada com a chave do sandbox nunca é aceita para um pagamento live, e vice-versa.
Notificações de pagamento
Notification URL: mostra o endereço para onde a PayU envia as notificações. Com URLs amigáveis, ele se parece com https://your-shop/module/wcp_payu_payment/webhook, possivelmente com um código de idioma. O módulo o envia à PayU com cada pagamento, então não há nada a configurar no painel da PayU. Certifique-se de que ele esteja acessível pela internet (não bloqueado por firewall ou autenticação HTTP). As notificações também funcionam enquanto a loja está em modo de manutenção e não são bloqueadas pela restrição de países da sua loja.
Avançado
Receive payments automatically: recebe automaticamente os pagamentos aguardando confirmação. Isso só importa se o recebimento automático estiver desligado para o seu POS no painel da PayU: os pagamentos ficam então aguardando confirmação (WAITING_FOR_CONFIRMATION). Com esta opção ativada, o módulo recebe esses pagamentos imediatamente e o pedido é criado quando a PayU informa que o pagamento foi concluído. Quando ela está desativada, ou se o recebimento falhar, o pedido é criado em Awaiting PayU payment confirmation e você recebe ou cancela o pagamento pelos botões no bloco da PayU do pedido. Padrão: ativado.
Logging: registra eventos técnicos (números de carrinho e de pedido, IDs de pedidos PayU, status, erros; sem chaves nem dados pessoais) no arquivo logs/wc_pu_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados; os demais eventos apenas enquanto esta opção estiver ativada. 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 seus dados de pagamento (transações PayU, reembolsos, status de pedido) nunca são excluídos. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe a opção de pagamento (por padrão PayU) e vê a descrição e a nota Você será redirecionado para a PayU para concluir o pagamento (BLIK, transferência bancária, cartão e outros métodos). Após a confirmação, o módulo cria um pedido PayU pelo total do carrinho na moeda do carrinho, com a descrição Cart #, o número do carrinho e o nome da sua loja, e com os produtos, o frete e o embrulho para presente para exibição na página da PayU. O e-mail, o nome e o telefone do cliente são enviados à PayU. O idioma da página da PayU segue o idioma da loja quando a PayU o suporta; caso contrário, é usado o inglês. O cliente é direcionado para a página da PayU, escolhe um método lá e paga. Neste ponto, ainda não existe nenhum pedido.
Cada tentativa de pagamento recebe seu próprio pedido PayU. Quando o cliente tenta novamente, o pagamento PayU anterior não concluído do carrinho é cancelado na PayU, de modo que um link de pagamento antigo não pode ser pago duas vezes. Se o pagamento anterior já estiver pago, o pedido é criado em vez de um novo pagamento.
O retorno à sua loja, por si só, nunca paga um pedido. O pedido só é marcado como pago depois que a PayU confirma: 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 quando o cliente retorna (no máximo uma vez a cada 10 segundos por carrinho). O pedido PayU precisa ter sido criado para este carrinho, e o valor e a moeda devem coincidir. O módulo trata estes status da PayU:
Após um pagamento confirmado, o cliente vê a página padrão de confirmação do pedido. Para um pedido aguardando confirmação ou em espera, a página acrescenta Seu pagamento está sendo verificado. Enviaremos um e-mail assim que ele for confirmado. Se o pagamento desse pedido for cancelado depois, a página mostra Seu pagamento PayU não foi concluído. Entre em contato conosco sobre este pedido.
Se a PayU ainda não tiver confirmado o pagamento quando o cliente retornar, uma página Payment confirmation mostra Ainda não recebemos a confirmação do pagamento da PayU. Se o pagamento foi interrompido, você pode tentar novamente: (ou, quando a PayU informou um erro, O pagamento não foi concluído. Você pode tentar novamente:) com os botões Pay again e Check again. A notificação cria o pedido assim que chegar. Se o pagamento foi cancelado, o cliente volta à finalização de compra com O pagamento não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. O carrinho é mantido.
Se a PayU não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com Erro de pagamento. Tente novamente ou escolha outro método de pagamento. O motivo técnico é gravado no registro. Se as chaves do modo atual estiverem faltando, a mensagem é O gateway de pagamento não está configurado corretamente. Entre em contato com o administrador.
Se um cupom no carrinho deixar de ser válido entre o pagamento e a sua confirmação, ele é removido do pedido. O pedido então vai para PayU payment on hold com uma nota que cita o cupom, porque o cliente pagou o preço com o desconto.
O cliente escolhe o método de pagamento na página da PayU, não na sua finalização de compra. O módulo não tem formulário de cartão na sua loja, nem cartões salvos ou pagamentos com um clique, nem assinaturas, nem widgets de parcelamento ou crédito da PayU. Ele usa um ponto de venda por ambiente.
Pedidos e reembolsos
Status do pedido
Ainda sem pedido: o cliente foi enviado à PayU e não pagou, ou a PayU ainda não confirmou o pagamento. Existe apenas o carrinho.
Payment accepted: o pagamento foi confirmado. Ele é registrado com o ID do pedido PayU como ID da transação, e uma nota mostra o ID do pedido PayU, o valor e o ambiente (sandbox ou live).
Awaiting PayU payment confirmation: o pagamento está autorizado e aguarda você (recebimento automático desligado ou falhou). Nenhum pagamento foi registrado ainda.
PayU payment on hold: o valor ou a moeda pagos não coincidiram com o carrinho (o pedido não é marcado como pago), um cupom foi removido, um pagamento aguardando confirmação tinha outro valor, ou um pagamento foi concluído para um pedido que havia sido cancelado (o pagamento é registrado). A nota informa qual caso ocorreu. Verifique o pedido e atenda-o ou reembolse o pagamento.
Payment error: o pagamento de um pedido aguardando confirmação foi cancelado ou recusado.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Cada notificação é processada uma única vez: notificações repetidas não acrescentam notas nem alteram o pedido novamente. Se outro pagamento for concluído para um pedido já pago ou reembolsado, uma nota pede que você o reembolse no painel da PayU. Um pagamento aguardando confirmação em um pedido já pago ou encerrado é cancelado automaticamente, para que o dinheiro não seja cobrado duas vezes.
Bloco de pagamento PayU
A página do pedido mostra um bloco PayU payment com o ID do pedido PayU, o extOrderId, o status da PayU, o valor pago e reembolsado, um selo Sandbox para pagamentos no sandbox, o histórico de reembolsos e as PayU notes do pedido. As ações do bloco exigem o direito de editar pedidos; o acesso às páginas de Módulos não é necessário.
Pagamentos aguardando confirmação
Para um pedido com pagamento aguardando confirmação, o bloco mostra Receive PayU payment (waiting for confirmation) e Cancel PayU payment (release the funds). Depois que você confirma a pergunta, a ação é enviada à PayU com as chaves do ambiente do pagamento, acrescentada às notas com o seu nome, e o novo status da PayU é aplicado imediatamente: um pagamento recebido define o pedido como Payment accepted, e um cancelado, como Payment error.
Reembolsos
No bloco PayU payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via PayU. Confirme a pergunta Reembolsar este valor pela PayU? Esta ação não pode ser desfeita. Reembolsos totais e parciais são suportados. O reembolso é enviado para o pedido PayU que foi efetivamente pago, com as chaves do ambiente do pagamento, então essas chaves precisam estar preenchidas. Os reembolsos são feitos no valor e na moeda cobrados pela PayU: após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente efetivamente pagou, e não o total do pedido. O motivo é enviado como descrição do reembolso. Se a PayU recusar o reembolso, o bloco mostra o erro da PayU e nenhum reembolso é registrado. Um reembolso total define o pedido como Refunded. Um reembolso parcial não altera o status.
Os reembolsos são assíncronos na PayU. O módulo adiciona imediatamente uma nota com o ID e o status do reembolso na PayU; o status final chega depois como notificação da PayU e é acrescentado às notas e ao histórico de reembolsos. Se a PayU cancelar um reembolso, a nota informa que o dinheiro não foi devolvido ao cliente, e o valor pode ser reembolsado novamente.
O módulo não gera notas de crédito. Os botões padrão de reembolso 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 Payment é o primeiro bloco da página Modules > Module Manager > VibeFox PayU Payment > 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 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 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 pelas notificações, 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 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 Sandbox no modo sandbox, as chaves Live no modo live. Verifique se a moeda do carrinho é uma das moedas suportadas. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente. A página de configurações exibe um aviso quando há chaves faltando ou quando a moeda da loja não é suportada.
O pagamento foi feito, mas nenhum pedido foi criado: a PayU ainda não entregou a notificação, e a verificação de status na página de retorno não encontrou um pagamento concluído. Verifique se a Notification URL exibida nas configurações está acessível pela internet. Ative Logging para ver o que chega. O cliente também pode clicar em Check again na página Payment confirmation.
A notificação responde Invalid signature: a notificação não foi assinada com a Second Key de nenhum dos dois 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 outro ambiente, diferente do ambiente do pagamento.
A notificação responde Ignored: unknown PayU order: o pedido PayU não foi criado por esta loja, por exemplo outra loja no mesmo POS. A PayU deixa de tentar novamente.
A notificação responde Busy, retry later: o carrinho estava sendo confirmado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A PayU repete a notificação. Ative Logging para ver o motivo.
A URL de notificação mostra POST expected no navegador: isso é normal. A URL aceita apenas notificações da PayU.
O cliente vê Payment error ao escolher a PayU: ative Logging e veja o campo Log na página do módulo. O registro mostra o código HTTP e o status da PayU. Não foi possível autenticar na PayU (verifique o OAuth client ID / secret). significa chaves OAuth erradas do modo atual.
O pedido está em PayU payment on hold: leia as notas no bloco PayU payment (veja Status do pedido), depois atenda o pedido ou reembolse o pagamento.
O pedido está em Awaiting PayU payment confirmation: o recebimento automático está desligado para o seu POS e o pagamento aguarda você. Use Receive PayU payment ou Cancel PayU payment no bloco da PayU.
O reembolso falha: Este pedido não tem um pagamento PayU concluído. Não é possível processar o reembolso. significa que a PayU ainda não concluiu um pagamento para o pedido. Uma mensagem informando que faltam as chaves Sandbox ou Live significa que o pagamento foi feito nesse ambiente e que as chaves dele não estão preenchidas. Insira-as e tente novamente.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox PayU Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Os tokens de acesso PayU em cache 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. As transações e reembolsos da PayU e os status de pedido Awaiting PayU payment confirmation e PayU 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 IDs de transação.
PayU é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela PayU.