VibeFox PayU LATAM for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin recusa a ativação sem ele; se o WooCommerce for desativado depois, o plugin não executa nenhuma ação e mostra um aviso na administração.

PHP: 8.0 ou superior.

Currency: o pedido 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.

PayU Latam account: 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 vende e a chave de API. Eles estão no módulo PayU (o painel de comerciante da PayU), em Settings > Technical configuration (ID de comerciante, chave de API) e Accounts (ID de conta). Para testes, a PayU publica credenciais públicas do ambiente de teste e cartões de teste na página "Test your solution" da documentação para desenvolvedores. API Login e outras credenciais de API não são necessários, pois o pagamento é feito na página hospedada pela PayU.

Internet access to your site: a PayU envia o resultado do pagamento à sua loja pelos próprios servidores, portanto o site deve estar acessível pela internet (não pode ser um site local, protegido por senha ou por uma página de manutenção).

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

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > PayU LATAM > Manage, ou clique em Settings abaixo do nome do plugin na página de plugins.

4. Digite sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Digite as credenciais de teste e de produção (veja Configuração). Não é necessário configurar uma URL de confirmação na PayU.

6. Ative Enable/Disable e salve. Mantenha Sandbox ativado até fazer um pagamento de teste, depois desmarque para aceitar pagamentos reais com as credenciais de produção.

Configuração

Todas as configurações estão em uma página: WooCommerce > Settings > Payments > PayU LATAM. Acima dos campos, a página avisa quando o modo de teste está ativado (Sandbox mode. Os pagamentos vão para o ambiente de teste da PayU e nenhum dinheiro real é cobrado.), quando faltam o ID de comerciante, o ID de conta ou a chave de API do ambiente atual e quando a PayU LATAM não processa a moeda da loja. Nos dois últimos casos, PayU LATAM não aparece na finalização de compra. Na lista de métodos de pagamento, PayU LATAM é marcado como precisando de configuração até que as três credenciais do ambiente atual sejam preenchidas. Espaços no início ou no final de uma credencial são ignorados.

Geral

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

Title: o título do método de pagamento mostrado ao cliente durante a finalização de compra. Padrão: PayU LATAM.

Description: a descrição do método de pagamento mostrada ao cliente durante a 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: Enable the PayU sandbox (test mode). Os pagamentos vão para o ambiente de teste da PayU com as credenciais de teste abaixo, sem cobrança de dinheiro real. Quando desativado, são usados as credenciais e o checkout de produção da PayU. Padrão: on.

Credenciais de produção

Encontre-as no módulo PayU: Settings > Technical configuration (ID de comerciante, chave de API) e Accounts (ID de conta do país em que você vende). A seção tem um link para o painel de comerciante da PayU.

Merchant ID: o identificador numérico do seu comércio na 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 notificações da PayU.

Credenciais de teste

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

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

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

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

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 de teste, e a de um pagamento de produção com os valores de produção, para que os pagamentos pendentes continuem funcionando após a troca. Ao atualizar da versão 1.0, que tinha um único conjunto de credenciais, os valores antigos são copiados para os campos de teste se o modo de teste estava ativado. Confira as configurações após atualizar.

URL de confirmação

Esta seção mostra a URL para a qual a PayU informa cada resultado de pagamento. Ela se parece com https://your-site/wc-api/payu_lp/. O plugin a envia à PayU com cada pagamento, portanto não há nada para configurar na PayU. A página deve estar acessível pela internet. A PayU assina a confirmação 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 para o pedido são rejeitadas. O plugin trata estes estados de transação da PayU:

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

6 (declined), 5 (expired), 104 (error): o pagamento falhou. Um pedido não pago referente à última tentativa é marcado como Malsucedido.

7 and other pending states: o pagamento está pendente, por exemplo um pagamento em dinheiro ou bancário que o cliente ainda não concluiu. O pedido fica em espera.

Outros estados são apenas adicionados como nota do pedido. Sem a confirmação, um pedido nunca é marcado como pago: permanece Pagamento pendente.

Avançado

Debug log: Log payment requests and PayU notifications grava detalhes em WooCommerce > Status > Logs, origem wcp_payu_latam_payment, sem chaves nem dados pessoais. Erros e notificações rejeitadas são sempre registrados. Padrão: off.

Delete data: Delete the settings and logs when the plugin is deleted. Desativar o plugin nunca exclui nada. Os dados PayU salvos nos pedidos são mantidos. Padrão: off.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão PayU LATAM) e faz o pedido. No bloco de Finalização de compra em modo de teste, ele vê Sandbox mode: no real payment is made. O pedido permanece Pagamento pendente, e o cliente vai para uma página de pagamento da sua loja com o texto Thank you for your order. You are being redirected to PayU LATAM to complete the payment… A página envia automaticamente um formulário assinado à página PayU WebCheckout. Se isso não acontecer, o cliente clica em Pay with PayU LATAM, ou em Cancel order para cancelar o pedido.

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

Cada visita à página de pagamento inicia uma nova tentativa com sua própria referência (número do pedido e marca de tempo). As últimas 30 tentativas do pedido são guardadas: se o cliente pagar em uma aba antiga da PayU, o pagamento ainda será aceito.

O pedido só é marcado como pago após a PayU confirmá-lo com a confirmação assinada. O retorno do cliente da PayU nunca marca um pedido como pago. Quando o cliente volta:

Após uma recusa, expiração ou erro assinado: o pedido é marcado como Malsucedido imediatamente, e o WooCommerce mostra sua página padrão de pagamento malsucedido com a opção de pagar novamente.

Sem uma transação PayU (o cliente saiu da página PayU): o cliente vai à página Pay for order com a mensagem Your PayU LATAM payment was not completed. You can try again or choose another payment method.

Nos demais casos: o cliente vê a página de pedido recebido. Enquanto o pedido está com Pagamento pendente, ela diz We are waiting for PayU LATAM to confirm your payment. You will receive an e-mail as soon as it is confirmed. Para um pedido em espera, ela diz 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.

Se faltam as credenciais do ambiente atual, o cliente vê PayU LATAM is not available right now. Please choose another payment method. Para uma moeda de pedido não suportada, a mensagem é PayU LATAM does not accept payments in seguida da moeda. Um pedido já pago não é pago novamente: a página de pagamento mostra This order has already been paid.

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 WooCommerce High-Performance Order Storage (HPOS).

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

Pedidos

Status dos pedidos

Pending payment: o cliente foi enviado à PayU e ainda não pagou, ou a PayU ainda não enviou a confirmação.

Processing: a PayU confirmou o pagamento e o valor e a moeda correspondem. A nota do pedido mostra a transação PayU, o valor, o método de pagamento e [sandbox] para pagamentos de teste. O ID da transação do pedido é o ID da transação PayU. Pedidos com apenas produtos virtuais baixáveis ficam como Concluído, como o WooCommerce faz por padrão.

On hold: a PayU informa o pagamento como pendente (dinheiro ou pagamento bancário), o valor pago ou a moeda não corresponde ao total do pedido, ou um pagamento foi aprovado para um pedido cancelado. A nota do pedido indica o motivo: confira o pagamento no módulo PayU e depois processe o pedido, restaure-o ou reembolse o pagamento.

Failed: a última tentativa de pagamento foi recusada, expirou ou terminou com um erro. A nota mostra a mensagem da PayU. O cliente pode pagar novamente. A recusa de uma tentativa anterior, ou de um pedido que já tem um pagamento aprovado, só é adicionada como nota.

Cada notificação é processada uma vez, com um bloqueio por pedido: notificações repetidas da PayU não duplicam notas, reduções de estoque ou e-mails. Se outra solicitação demorar demais para atualizar o pedido, a confirmação recebe uma resposta de erro e a PayU a envia novamente mais tarde. Um pedido pago, concluído ou reembolsado nunca é reaberto. Se chegar outro pagamento aprovado para um pedido já pago, uma nota informa isso: se o cliente pagou duas vezes, reembolse a duplicata no módulo PayU.

Reembolsos

Os reembolsos não são feitos pelo WooCommerce. Reembolse a transação no módulo PayU e, se necessário, registre o reembolso manualmente no WooCommerce.

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 LATAM. 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 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 sua conta vibefox.net.

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

Sem uma chave ativa, PayU LATAM não aparece para os 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 de loja conectados ainda veem o método de pagamento, marcado (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 de plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados.

Quando a 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

PayU LATAM não aparece na finalização de compra: confira 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: credenciais de teste quando Sandbox está ativado, de produção quando está desativado. Confira se a moeda da loja (ou do pedido na página de pagamento do pedido) é ARS, BRL, CLP, COP, MXN, PEN ou USD. A página de configurações mostra um aviso para cada um desses problemas.

O pagamento foi feito, mas o pedido permanece Pending payment: a confirmação PayU não chegou à sua loja ou foi rejeitada. Confira se a URL de confirmação nas configurações está acessível pela internet (sem site local, modo de manutenção, firewall ou proteção por senha). Veja as confirmações rejeitadas em WooCommerce > Status > Logs, origem wcp_payu_latam_payment. A PayU reenvia a confirmação após qualquer resposta de erro.

A confirmação recebe Invalid signature: ela não foi assinada com a chave de API do ambiente do pagamento. Confira API Key para pagamentos de produção e Sandbox API key para pagamentos de teste.

A confirmação recebe Merchant mismatch: seu ID de comerciante difere de Merchant ID ou Sandbox merchant ID do ambiente do pagamento. Digite o ID de comerciante da conta PayU que processa os pagamentos.

A confirmação recebe Gateway not configured: falta a chave de API ou o ID de comerciante do ambiente do pagamento, por exemplo porque as credenciais de teste foram removidas enquanto um pagamento de teste estava pendente. Digite-os novamente; a PayU tenta confirmar de novo.

A confirmação recebe Busy, retry later: outra solicitação estava atualizando o pedido ao mesmo tempo. Nada foi alterado, e a PayU envia a confirmação novamente.

A confirmação recebe Unknown reference: a referência de pagamento não pertence a um pedido PayU LATAM desta loja, por exemplo porque o pedido foi alterado para outro método de pagamento ou excluído.

O pedido está On hold: leia a nota do pedido. O pagamento ainda está pendente na PayU (dinheiro ou pagamento bancário), o valor pago ou a moeda diferia do pedido, ou o pagamento chegou após o cancelamento do pedido. Confira a transação no módulo PayU.

Outras moedas ou campos do formulário: desenvolvedores podem alterar a lista de moedas com o filtro payu_lp_supported_currencies, o ícone da finalização de compra com o filtro payu_lp_icon e os campos do formulário WebCheckout com o filtro payu_lp_payment_fields.

O bloco de licença mostra um erro: siga a mensagem no bloco. Por exemplo, se a chave já é usada em outro domínio, libere uma vaga na sua conta vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças estiver inacessível, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative e exclua na página Plugins. A chave e o status da licença deste plugin são sempre removidos. As configurações do gateway e os logs deste plugin só são removidos se Delete data estava ativado. Caso contrário, ficam para uma reinstalação posterior. Pedidos existentes mantêm suas notas de pagamento, referências PayU e IDs de transação.

PayU é uma marca comercial de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela PayU.