VibeFox PayU LATAM for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões anteriores do PHP.

Moeda: o carrinho deve estar em ARS, BRL, CLP, COP, MXN, PEN ou USD, as moedas processadas pela PayU Latam na Argentina, Brasil, Chile, Colômbia, México, Panamá e Peru. Em outras moedas, o método de pagamento fica oculto na finalização de compra.

Conta PayU Latam: você precisa de três valores do seu comércio na PayU: o ID de comerciante, o ID de conta do país em que você vende e a chave de API. Eles estão no módulo PayU (o painel do comerciante PayU), em Settings > Technical configuration (merchant ID, API key) e Accounts (account ID). Para testes, a PayU publica credenciais públicas de teste e cartões de teste na página "Test your solution" da documentação para desenvolvedores. O API Login e outras credenciais de API não são necessárias, pois o pagamento é feito na página hospedada pela PayU e o módulo nunca chama a API da PayU.

Acessibilidade da loja pela internet: a PayU envia o resultado do pagamento à sua loja a partir dos servidores dela, então a loja precisa estar acessível pela internet (não pode ser um site local nem estar protegida por senha).

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 envio terminar, clique em Configure, ou encontre depois VibeFox PayU LATAM Payment na lista de módulos e clique em Configure.

3. Insira sua chave de licença VibeFox em License key no bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).

4. Insira as credenciais de teste e suas credenciais de produção (veja Configuração). Não é preciso configurar nenhuma URL de confirmação na PayU.

5. Ative Enable/Disable e clique em Save. Mantenha Sandbox ativado até fazer um pagamento de teste e depois desative-o para aceitar pagamentos reais com as credenciais de produção.

Na instalação, o módulo cria dois status de pedido: Awaiting PayU LATAM payment e PayU LATAM payment on hold. O PrestaShop oferece um novo método de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-lo em Payment > Preferences. Um país habilitado depois também precisa ser marcado ali para o módulo.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox PayU LATAM Payment > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Sandbox mode. Payments go to the PayU sandbox and no real money is charged. enquanto o ambiente de teste estiver ativo; um erro quando o ID de comerciante, o ID de conta ou a chave de API do ambiente atual estiverem ausentes; e um aviso quando a PayU LATAM não processa a moeda padrão da loja. Enquanto houver credenciais ausentes, a PayU LATAM não aparece na finalização de compra. Espaços no início ou no fim de uma credencial são ignorados. A página não salva um Title vazio e mostra Enter a title for the payment method.

PayU LATAM

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

Title: o título do método de pagamento exibido ao cliente na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: PayU LATAM. Obrigatório.

Description: a descrição do método de pagamento exibida ao cliente na finalização de compra. Padrão: Pay with a card, cash or bank transfer on the secure PayU page. You will be redirected to PayU to complete your payment.

Ambiente

Sandbox: os pagamentos vão para o ambiente de teste da PayU com as credenciais de teste abaixo, e nenhum dinheiro real é cobrado. Quando desativado, são usadas as credenciais de produção e a página de pagamento de produção da PayU. Padrão: ativado. Enquanto estiver ativado, os clientes veem Sandbox mode: no real money is charged. abaixo do método de pagamento.

Credenciais de produção

Encontre-as no módulo PayU: Settings > Technical configuration (merchant ID, API key) e Accounts (account ID do país em que você vende). A seção leva ao painel do comerciante PayU.

Merchant ID: o identificador numérico do seu comércio PayU.

Account ID: o identificador da conta PayU. Há uma conta por país.

API Key: a chave secreta usada para assinar pagamentos e verificar as notificações da PayU.

Credenciais de teste

A PayU publica credenciais públicas de teste e cartões de teste para o seu ambiente de teste. A seção leva à página "Test your solution" da documentação da PayU.

Sandbox merchant ID: o ID de comerciante para o ambiente de teste da PayU.

Sandbox account ID: o ID de conta para o ambiente de teste da PayU.

Sandbox API key: a chave de API para o ambiente de teste da PayU.

As chaves de API salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-la.

Clear saved secrets: marque API Key ou Sandbox API key e clique em Save para remover a chave salva. Um campo vazio mantém o valor salvo.

Cada tentativa de pagamento guarda seu ambiente. A confirmação de um pagamento de teste é verificada com a chave de API e o ID de comerciante do ambiente de teste, e a de um pagamento real com os de produção, de modo que os pagamentos pendentes continuam funcionando após a troca. Um pagamento de teste confirmado depois da troca é marcado como [sandbox] nas notas do pedido.

URL de confirmação

Esta seção mostra a URL para a qual a PayU informa cada resultado de pagamento. Com URLs amigáveis, ela tem esta aparência: https://your-shop/module/wcp_payu_latam_payment/confirmation, possivelmente com um código de idioma como /en/. O módulo a envia à PayU com cada pagamento, então não há nada para configurar na PayU. A URL deve ser acessível pela internet. Ela também funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja. A confirmação é assinada pela PayU com sua chave de API. Confirmações sem assinatura válida, com outro ID de comerciante ou com uma referência de pagamento que esta loja não emitiu são rejeitadas. O módulo trata estes estados de transação da PayU:

4 (approved): o pagamento foi feito. O pedido é criado como pago quando o valor e a moeda correspondem ao carrinho.

6 (declined), 5 (expired), 104 (error): o pagamento falhou. Nenhum pedido é criado e o carrinho é mantido.

7, 10, 12, 14, 15, 18 (pending): o pagamento está aguardando, por exemplo um pagamento em dinheiro ou boleto que o cliente ainda não concluiu. O pedido é criado em Awaiting PayU LATAM payment.

Os demais estados são apenas adicionados como nota. Sem a confirmação, nenhum pedido é criado.

Avançado

Debug log: registra as solicitações de pagamento e as notificações da PayU em logs/payu_lp_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves e dados pessoais não são registrados. Erros e notificações rejeitadas são sempre registrados, mesmo quando esta opção está desativada. Padrão: desativado.

Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.

Delete data: exclui as configurações e os logs quando o módulo é desinstalado. Os dados da PayU dos pedidos (tentativas de pagamento) e os status de pedido são mantidos. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão PayU LATAM) e confirma. Uma página da sua loja mostra You are being redirected to PayU LATAM to complete the payment... e envia automaticamente um formulário assinado para a página WebCheckout da PayU. Se isso não acontecer, o cliente clica em Pay with PayU LATAM, ou em Back to checkout para voltar. Nesse momento, ainda não existe pedido.

O formulário contém o total e a moeda do carrinho, o imposto e a base de cálculo do imposto do carrinho (ambos 0 para carrinhos sem imposto, para que a PayU não adicione um IVA padrão), a descrição Cart # com o número do carrinho e o nome da sua loja, além do e-mail, nome, telefone e endereço de cobrança do cliente. A página da PayU abre em espanhol, português ou inglês, conforme o idioma do carrinho. Na página da PayU, o cliente paga com qualquer método habilitado na sua conta PayU.

Cada visita à página de pagamento inicia uma nova tentativa de pagamento com referência própria (PS, o número do carrinho e um carimbo de data/hora). Tentativas anteriores são guardadas: se o cliente pagar em uma aba antiga da PayU, o pagamento ainda é aceito.

O pedido só é marcado como pago depois que a PayU confirma com a confirmação assinada. O cliente que volta da PayU nunca marca um pedido como pago. Quando o cliente volta:

Após uma recusa, expiração ou erro assinados: o cliente volta à finalização de compra com Your PayU LATAM payment was not approved, o motivo da PayU, se houver, e You can try again or choose another payment method. O carrinho é mantido.

Sem transação na PayU (o cliente saiu da página da PayU): o cliente volta à finalização de compra com Your PayU LATAM payment was not completed. You can try again or choose another payment method.

O pedido já existe: o cliente vê a página padrão de confirmação do pedido. Para um pedido em Awaiting PayU LATAM payment, aparece Your PayU LATAM payment is pending (for example, a cash or bank payment that has not been completed yet). We will process the order as soon as PayU confirms the payment. Para um pedido em espera, aparece We have received your PayU LATAM payment and are reviewing it. We will contact you if anything is needed. Para um pedido em Payment error, aparece Your PayU LATAM payment was not approved. Please contact us.

A PayU ainda não confirmou: uma página mostra We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. (ou o texto de pendente acima, para um pagamento em dinheiro ou boleto) com um botão Check again. A confirmação cria o pedido assim que chegar.

Se as credenciais do ambiente atual estiverem ausentes, o cliente vê PayU LATAM is not available right now. Please choose another payment method. Para uma moeda de carrinho não suportada, a mensagem é PayU LATAM does not accept payments in seguida da moeda. Um carrinho que já tem pedido não é cobrado de novo: o cliente vai para a página de confirmação do pedido.

O módulo não tem formulário de pagamento na loja, nem reembolsos pelo PrestaShop, cartões salvos, assinaturas ou configurações de parcelamento (a PayU mostra as parcelas na própria página). Ele não consulta a API da PayU para saber o status do pagamento: somente a confirmação assinada atualiza o pedido.

Pedidos

Status do pedido

Ainda sem pedido: o cliente foi enviado à PayU e não pagou, o pagamento foi recusado ou a PayU ainda não enviou a confirmação. Existe apenas o carrinho.

Payment accepted: a PayU confirmou o pagamento e o valor e a moeda correspondem. O pagamento é registrado com o ID da transação PayU, e uma nota mostra a transação, o valor, o método de pagamento e [sandbox] para pagamentos de teste.

Awaiting PayU LATAM payment: a PayU informa o pagamento como pendente (pagamento em dinheiro ou boleto). O pedido passa para Payment accepted quando a PayU confirma o pagamento.

PayU LATAM payment on hold: o valor ou a moeda pago não corresponde ao total do carrinho, ou um pagamento foi aprovado para um pedido que havia sido cancelado. O pagamento é registrado se estiver na moeda do pedido. A nota indica qual é o caso: verifique o pagamento no módulo PayU e depois processe o pedido, restaure-o ou reembolse o pagamento.

Payment error: um pagamento pendente da última tentativa foi depois recusado, expirou ou terminou com erro. A nota mostra a mensagem da PayU. Este carrinho não pode ser pago novamente: o cliente faz um novo pedido. Uma recusa de uma tentativa anterior, ou de um pedido que já tem pagamento aprovado, é apenas adicionada como nota.

Cada notificação é processada uma vez, com um bloqueio por carrinho: notificações repetidas da PayU não criam um segundo pedido nem adicionam notas duas vezes. Um pedido pago nunca é reaberto ou rebaixado. Se chegar outro pagamento aprovado para um pedido já pago, uma nota avisa: se o cliente pagou duas vezes, reembolse a duplicata no módulo PayU.

Bloco de pagamento PayU LATAM

A página do pedido mostra um bloco PayU LATAM payment com a referência, o ID da transação, a referência PayU, o status e o estado PayU, o valor solicitado, o valor informado pela PayU, o método de pagamento, a mensagem da PayU, um selo SANDBOX para pagamentos de teste, a lista de todas as tentativas de pagamento do carrinho e as PayU LATAM notes do pedido.

Reembolsos

Os reembolsos não são feitos pelo PrestaShop. Reembolse a transação no módulo PayU e depois registre o reembolso manualmente no PrestaShop.

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 LATAM Payment é o primeiro bloco de Modules > Module Manager > VibeFox PayU LATAM 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-latam e o link Manage licenses and domains in your account, que abre a sua conta vibefox.net. Apenas 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 que o endereço da loja mudar, ou depois que você 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 único 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 LATAM 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 loja do PrestaShop 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. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados pela confirmação da PayU e pelo retorno do cliente.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 e depois uma vez por semana. Nenhum cron job é necessário. 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 LATAM não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o ID de comerciante, o ID de conta e a chave de API do ambiente atual estão preenchidos: as credenciais de teste quando Sandbox está ativado, as de produção quando está desativado. Verifique se a moeda do carrinho é ARS, BRL, CLP, COP, MXN, PEN ou USD. 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.

O pagamento foi feito, mas nenhum pedido foi criado: a confirmação da PayU não chegou à sua loja ou foi rejeitada. Verifique se a URL de confirmação mostrada nas configurações é acessível pela internet (sem site local, firewall ou proteção por senha). Veja o campo Log na página do módulo para ver confirmações rejeitadas. A PayU envia a confirmação novamente após qualquer resposta de erro.

A confirmação responde Invalid signature: a confirmação não foi assinada com a chave de API do ambiente do pagamento. Verifique API Key para pagamentos reais e Sandbox API key para pagamentos de teste.

A confirmação responde Merchant mismatch: o ID de comerciante da confirmação é diferente de Merchant ID ou de Sandbox merchant ID do ambiente do pagamento. Insira o ID de comerciante da conta PayU que processa os pagamentos.

A confirmação responde Gateway not configured: a chave de API ou o ID de comerciante do ambiente do pagamento está ausente, por exemplo porque as credenciais de teste foram removidas enquanto um pagamento de teste estava pendente. Insira-as novamente; a PayU tentará a confirmação de novo.

A confirmação responde Retry: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). Nada foi alterado, e a PayU envia a confirmação novamente. Veja o Log para o motivo.

A confirmação responde Unknown reference: a referência de pagamento não foi emitida por esta loja.

A URL de confirmação mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições da PayU.

O cliente vê This payment method is not available: o módulo não está permitido para o país, a moeda ou o grupo do cliente em Payment > Preferences, ou Enable/Disable está desativado.

O pedido está em PayU LATAM payment on hold: leia as notas no bloco PayU LATAM payment. O valor ou a moeda pagos eram diferentes do carrinho, ou o pagamento chegou depois que o pedido foi cancelado. Verifique a transação no módulo PayU.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox PayU LATAM Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data estiver ativado, as configurações e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As tentativas de pagamento e os status de pedido Awaiting PayU LATAM payment e PayU LATAM payment on hold são sempre mantidos, para que uma confirmação tardia da PayU de uma tentativa antiga seja reconhecida após uma reinstalação. Pedidos existentes mantêm suas notas de pagamento, referências PayU e IDs de transação.

PayU é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela PayU.