VibeFox PayU LATAM for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado com a versão 3.0.5.0) ou 4.0.2 e posteriores (testado com a versão 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: a moeda da finalização de compra do cliente deve ser ARS, BRL, CLP, COP, MXN, PEN ou USD, as moedas processadas pela PayU Latam na Argentina, no Brasil, no Chile, na Colômbia, no México, no Panamá e no 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 merchant ID, o account ID do país em que você vende e a chave de API. Eles ficam no painel do comerciante da PayU, em Settings > Technical configuration (merchant ID, API key) e Accounts (account ID). Para testes, a PayU publica credenciais públicas de sandbox e cartões de teste na página "Test your solution" da documentação para desenvolvedores. As API Login e demais credenciais de API não são necessárias, porque o pagamento é feito na página hospedada pela PayU e a extensão nunca chama a API da PayU.

Acesso à internet para a sua loja: a PayU envia o resultado do pagamento para a 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 domínio.

Instalação

O download é um único arquivo zip com os pacotes para as duas versões do OpenCart. Descompacte-o no seu computador. Ele contém o README.txt, o pacote do OpenCart 3 wcp_payu_latam_payment-oc3-(version).ocmod.zip e o pacote do OpenCart 4 wcp_payu_latam_payment.ocmod.zip. Instale apenas o pacote da sua versão do OpenCart. A chave de licença é a mesma para as duas versões.

OpenCart 3

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_payu_latam_payment-oc3-(version).ocmod.zip. A extensão não tem modificações OCMOD, então Extensions > Modifications não precisa ser atualizado. Em vez do instalador, você pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Acesse Extensions > Extensions e escolha o tipo Payments. Localize VibeFox PayU LATAM Payment e clique em Install (o botão verde +). O seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

3. Clique em Edit (o botão com o lápis) para abrir a página de configurações. Cole a sua chave de licença VibeFox em License key, no bloco de licença no topo da página, e clique em Activate (veja Chave de licença).

4. Informe as credenciais de sandbox e as 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.

OpenCart 4

1. No admin, acesse Extensions > Installer, clique em Upload e escolha o arquivo wcp_payu_latam_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão a partir do nome do arquivo, e um pacote renomeado não funciona.

2. O pacote aparece na lista de extensões instaladas, na mesma página. Clique em Install (o botão verde +) ao lado dele.

3. Acesse Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox PayU LATAM Payment, clique em Install (o botão verde +) e depois em Edit (o botão com o lápis).

4. Informe a chave de licença e as credenciais da PayU como nos passos 3 a 5 do OpenCart 3. A página de configurações e os campos são os mesmos nas duas versões. Só a URL de confirmação é diferente (veja URL de confirmação).

Uma nova instalação começa com o método de pagamento desativado e o sandbox ativado.

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit. As seções ficam listadas à esquerda; o botão Save sob a lista salva a página inteira. Acima das configurações, a página mostra Sandbox mode. Payments go to the PayU sandbox and no real money is charged. enquanto o sandbox estiver ativado; um erro quando o merchant ID, o account ID ou a chave de API do ambiente atual estiver ausente (o PayU Latam deixa de ser oferecido na finalização de compra); e um aviso quando o PayU Latam não processa a moeda padrão da loja. Sem a permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Ao salvar, Title não pode estar vazio nem ter mais de 128 caracteres (a página mostra Enter a title for the payment method (at most 128 characters).), Sort Order precisa ser um número inteiro (números negativos são permitidos), Total precisa ser um número igual ou maior que 0, e a zona geográfica e os status de pedido precisam existir. Caso contrário, nada é salvo. Espaços no início ou no fim de uma credencial são ignorados.

PayU LATAM

Enable/Disable: Enable PayU LATAM liga ou desliga o método de pagamento. Padrão: desligado.

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Também é o nome do método de pagamento gravado no pedido. Padrão: PayU LATAM. Obrigatório, no máximo 128 caracteres.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. 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.

Sort Order: a posição do PayU LATAM entre os métodos de pagamento na finalização de compra. Deixe em branco ou informe um número inteiro.

Geo Zone: oferecer o PayU LATAM apenas para endereços de pagamento na zona geográfica selecionada. Padrão: All zones. As zonas geográficas são configuradas em System > Localisation > Geo Zones.

Total: o total da finalização de compra, na moeda padrão da loja, que um pedido precisa atingir para que o PayU LATAM seja oferecido. Deixe em branco para oferecer o PayU LATAM em qualquer valor.

Ambiente

Sandbox: os pagamentos vão para o sandbox da PayU com as credenciais de sandbox, e nenhum valor 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, o cliente vê Sandbox mode: no real money is charged. na etapa Confirm Order.

Credenciais de produção

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

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

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

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

Credenciais de sandbox

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

Sandbox merchant ID: o merchant ID do sandbox da PayU.

Sandbox account ID: o account ID do sandbox da PayU.

Sandbox API key: a chave de API do sandbox 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 se quiser alterá-lo. Para remover uma chave salva, marque Clear saved secret on save abaixo do campo e clique em Save.

Cada tentativa de pagamento guarda o seu ambiente. A confirmação de um pagamento de sandbox é verificada com a chave de API e o merchant ID do sandbox, e a de um pagamento de produção com os de produção; assim, os pagamentos pendentes continuam funcionando depois que você troca de ambiente. Os pagamentos de sandbox são marcados como tal nas notas do pedido.

URL de confirmação

Esta seção mostra a URL para a qual a PayU informa cada resultado de pagamento. No OpenCart 3 ela tem o formato https://your-store/index.php?route=extension/payment/wcp_payu_latam_payment/confirmation; no OpenCart 4, https://your-store/index.php?route=extension/wcp_payu_latam_payment/payment/wcp_payu_latam_payment.confirmation. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. A extensão a envia para a PayU em cada pagamento, então não há nada a configurar na PayU. A URL precisa estar acessível pela internet. Ela também funciona quando a loja está em modo de manutenção (no OpenCart 4, pela ação de inicialização da extensão, que também deixa passar o retorno do cliente da PayU). A confirmação é assinada pela PayU com a sua chave de API. Confirmações sem assinatura válida, com outro merchant ID ou com uma referência de pagamento que esta loja não emitiu são rejeitadas. A extensão trata estes status de transação da PayU:

Os demais status são apenas adicionados como nota. Sem a confirmação, o pedido não recebe nenhum status.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). O pedido só recebe um status depois da confirmação assinada da PayU. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: um pagamento aprovado (status 4 da PayU) com o valor e a moeda esperados. Padrão: Processing.

Awaiting Payment Status: um pagamento pendente (status 7, 10, 12, 14, 15, 18, por exemplo um pagamento em dinheiro ou boleto ainda não concluído). O pedido recebe Order Status After Payment quando a PayU o confirma. Padrão: Pending.

On Hold (Review) Status: a PayU aprovou um pagamento, mas com valor ou moeda diferentes do pedido, ou para um pedido que tinha sido cancelado. Uma nota mostra os detalhes; o pedido não é marcado como pago. Padrão: Pending, porque o OpenCart não tem um status On hold. Você pode criar um status próprio em System > Localisation > Order Statuses e selecioná-lo aqui.

Failed Payment Status: um pagamento pendente da última tentativa que a PayU depois informou como recusado, expirado ou com falha. Padrão: Failed.

Cancelled Order Status: o status que a sua loja usa para pedidos cancelados. Um pagamento aprovado para um pedido assim o coloca em On Hold (Review) Status, em vez de marcá-lo como pago. A extensão nunca define este status. Padrão: Canceled.

Avançado

Debug log: registra as solicitações de pagamento e as notificações da PayU em payu_lp_debug.log.php, na pasta de logs do OpenCart (storage/logs). O arquivo não pode ser aberto pela web e, ao atingir 5 MB, é movido para payu_lp_debug.old.log.php. Chaves e dados pessoais não são registrados. Erros e notificações rejeitadas são sempre registrados, mesmo com esta opção desligada. Padrão: desligado.

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

Delete data: quando ativado, desinstalar a extensão remove as configurações do gateway e o log. Os pedidos e os registros de pagamento da PayU (tentativas de pagamento) nunca são excluídos. Padrão: desligado.

Importar / Exportar

Export: Download JSON salva as configurações em um arquivo JSON. As chaves de API não são exportadas.

Import: cole o JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves de API salvas são mantidas.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, PayU LATAM). Na etapa Confirm Order, o cliente vê a sua descrição; o OpenCart cria o pedido nesta etapa, ainda sem status. No OpenCart 4 o cliente escolhe o método de pagamento com o botão Choose do bloco de métodos de pagamento, na janela Payment method options, e clica em Confirm Order no final da página de finalização de compra. Quando o cliente clica em Confirm Order, a extensão prepara um formulário de pagamento assinado, a página mostra You are being redirected to PayU LATAM to complete the payment... e envia o formulário automaticamente para a página WebCheckout da PayU. Se isso não acontecer, o cliente clica em Pay with PayU LATAM.

O formulário contém o total do pedido na moeda do pedido, o imposto e a base de cálculo do imposto do pedido (ambos 0 para 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 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 cliente. Na página da PayU, o cliente paga com qualquer método habilitado na sua conta PayU.

Cada clique em Confirm Order inicia uma nova tentativa de pagamento com referência própria (OC, o número do pedido e um carimbo de data/hora). No OpenCart 4 uma nova tentativa paga o mesmo pedido do checkout. As tentativas anteriores são lembradas: se o cliente pagar em uma aba antiga da PayU, o pagamento ainda é reconhecido.

O pedido só é marcado como pago depois que a PayU o confirma com a confirmação assinada. Em seguida, ele recebe o status da forma padrão do OpenCart, com os e-mails habituais de pedido e a atualização do estoque. O cliente que volta da PayU nunca marca um pedido como pago. Quando o cliente volta:

No OpenCart 4 essas mensagens são exibidas acima da página de finalização de compra.

No OpenCart 3, um novo pedido é criado sempre que a etapa Confirm Order é exibida; no OpenCart 4, o pedido do checkout é atualizado, mas um carrinho só é pago uma vez: se outro pedido do mesmo carrinho já estiver pago, aguardando pagamento ou em análise, o Confirm Order leva direto à página de sucesso. Uma alteração do carrinho, inclusive uma nova quantidade, conta como um novo carrinho que precisa de um pagamento próprio. Se as credenciais do ambiente atual estiverem ausentes, o cliente vê PayU LATAM is not available right now. Please choose another payment method.

No OpenCart 4, o pedido permanece na finalização de compra até que a página de sucesso seja exibida. Se esse pedido tiver sido fechado sem pagamento nesse meio-tempo (por exemplo, se o pagamento pendente falhou ou você o cancelou), o cliente volta à finalização de compra com a mensagem Your PayU LATAM payment was not approved e o motivo da PayU, se houver. Se o pedido foi pago e depois fechado pela loja, ou foi pago por um carrinho anterior que mudou desde então, a mensagem é Seu pedido anterior já está fechado. Confirme o pedido novamente: o carrinho será pago com um novo pedido. O próximo Confirm Order paga um novo pedido. Um pedido fechado nunca é mostrado como pago.

A extensão não tem formulário de pagamento no seu site, não faz reembolsos pelo OpenCart, não tem cartões salvos, assinaturas nem configurações de parcelamento (a PayU mostra as parcelas na própria página). Ela não consulta a API da PayU para saber o status do pagamento: apenas a confirmação assinada atualiza o pedido.

Pedidos

Status do pedido

Sem status (pedido ausente): o cliente foi enviado à PayU e não pagou, o pagamento foi recusado ou a PayU ainda não enviou a confirmação. Em Sales > Orders, esses pedidos só aparecem com o filtro Order Status definido como Missing Orders.

Order Status After Payment (default Processing): a PayU confirmou o pagamento e o valor e a moeda correspondem. Uma nota mostra a transação, o valor, o método de pagamento e se foi um pagamento de sandbox.

Awaiting Payment Status (default Pending): a PayU informa o pagamento como pendente (pagamento em dinheiro ou boleto). O pedido passa para Order Status After Payment quando a PayU confirma o pagamento, ou para Failed Payment Status se ele falhar. O OpenCart avisa o cliente sobre essas mudanças.

On Hold (Review) Status (default Pending): o valor ou a moeda pagos não correspondem ao total do pedido, ou um pagamento foi aprovado para um pedido que havia sido cancelado. A nota indica qual é o caso: confira o pagamento no painel da PayU e depois processe o pedido, restaure-o ou reembolse o pagamento.

Failed Payment Status (default Failed): um pagamento pendente da última tentativa foi depois recusado, expirou ou terminou com erro. A nota mostra a mensagem da PayU. A recusa de uma tentativa anterior, ou de um pedido que já tem um pagamento aprovado, é apenas adicionada como nota.

Cada notificação é processada uma única vez, sob um bloqueio por carrinho: notificações repetidas da PayU não alteram o pedido duas vezes nem adicionam notas em duplicidade. Um pedido pago nunca é rebaixado. Se chegar outro pagamento aprovado para um pedido já pago, ou para outro pedido do mesmo carrinho, uma nota no pedido pago informa isso: se o cliente pagou duas vezes, reembolse o duplicado no painel da PayU.

As notas são entradas do History do pedido que o cliente não vê.

Aba VibeFox PayU LATAM Payment

Em Sales > Orders, abra um pedido pago com PayU LATAM. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox PayU LATAM Payment mostra a Reference, o Transaction ID, a PayU reference, o Status e o status da PayU, o valor Requested, o Amount reported by PayU, o Payment method, a PayU message, um selo SANDBOX para pagamentos de sandbox, a lista de todas as Payment attempts do carrinho e as PayU LATAM notes do pedido. A aba é exibida para os usuários que têm acesso à extensão.

Reembolsos

Os reembolsos não são feitos pelo OpenCart. Reembolse a transação no painel da PayU e, em seguida, registre o reembolso manualmente no OpenCart.

Chave de licença

A extensão 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 em Extensions > Extensions > Payments > VibeFox PayU LATAM Payment > Edit, acima das configurações. Cole 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: opencart-payment-payu-latam e o link Gerencie licenças e domínios na sua conta, que abre a sua conta em vibefox.net. Somente usuários administradores com a permissão Modify para a extensão podem alterar a chave. Os textos do bloco seguem o idioma do admin (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 mudar o endereço da loja, ou de liberar uma vaga de domínio na sua conta, clique em Check now. Se o servidor de licenças estiver inacessível, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um domínio: o endereço da loja definido na configuração do OpenCart. Remover a chave da loja não libera a vaga de domínio. Libere-a na sua conta em vibefox.net.

Sem uma chave ativa, o PayU LATAM não é mostrado 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. Um usuário administrador logado no admin no mesmo navegador ainda vê o método de pagamento na loja, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar a extensão antes de comprar uma chave. No OpenCart 4 essa prévia não está disponível: a loja não enxerga o login do admin, então, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, um lembrete aparece no Dashboard do admin. Feche-o com × para ocultá-lo por 7 dias. Os 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, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente quando você abre o Dashboard ou a página Edit do admin: uma vez por dia nos primeiros 14 dias após a chave ser informada, depois uma vez por semana. Não é necessário cron job. Desinstalar a extensão sempre remove a chave de licença e o status da licença.

Solução de problemas

O PayU LATAM não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ligado e se o merchant ID, o account ID e a chave de API do ambiente atual estão preenchidos: as credenciais de sandbox quando Sandbox está ligado, as de produção quando está desligado. Verifique se a moeda do cliente é ARS, BRL, CLP, COP, MXN, PEN ou USD, se o endereço de pagamento está na Geo Zone selecionada e se o pedido atinge o Total definido nas configurações.

O pagamento foi feito, mas o pedido continua sem status: a confirmação da PayU não chegou à sua loja ou foi rejeitada. Verifique se a URL de confirmação mostrada nas configurações está acessível pela internet (sem site local, firewall ou proteção por senha). Veja o campo Log na página da extensão para localizar 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 de produção e Sandbox API key para pagamentos de sandbox.

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

A confirmação responde Gateway not configured: a chave de API ou o merchant ID do ambiente do pagamento está ausente, por exemplo porque as credenciais de sandbox foram removidas enquanto um pagamento de sandbox estava pendente. Informe-as novamente; a PayU vai repetir a confirmação.

A confirmação responde Retry: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o status do pedido não pôde ser definido. A PayU enviará a confirmação de novo. Veja o Log para o motivo.

A confirmação responde Unknown reference: a referência do 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. Please reload the checkout page.: a sessão da finalização de compra não corresponde mais ao pedido, ou Enable/Disable foi desligado nesse meio tempo. O cliente deve recarregar a finalização de compra.

O pedido está no status de análise: leia as notas na aba VibeFox PayU LATAM Payment. O valor ou a moeda pagos eram diferentes do pedido, ou o pagamento chegou depois de o pedido ter sido cancelado. Verifique a transação no painel da PayU.

Desinstalação

Acesse Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox PayU LATAM Payment. A chave de licença e o status da licença desta extensão são sempre removidos. O OpenCart sempre remove as próprias configurações da extensão: Enable/Disable, Sort Order, Geo Zone, Total e os status de pedido da seção Orders, que voltam aos padrões em uma nova instalação. O evento do OpenCart da extensão também é removido (no OpenCart 4, também os seus eventos e a sua ação de inicialização, que deixa passar a confirmação e o retorno do cliente no modo de manutenção). Se Delete data estiver ligado, as demais configurações do gateway (título, descrição, sandbox, credenciais, chave do debug log) e o log são removidos. Se estiver desligado, são mantidos para uma futura reinstalação. As tentativas de pagamento são sempre mantidas, de modo que uma confirmação tardia da PayU de uma tentativa antiga continua sendo reconhecida após uma reinstalação. Os pedidos existentes mantêm as suas notas de pagamento.

No OpenCart 4, para remover também os arquivos da extensão, depois da desinstalação vá em Extensions > Installer, clique em Uninstall (o botão laranja −) ao lado de VibeFox PayU LATAM Payment na lista de extensões instaladas e depois em Delete (o botão vermelho com a lixeira) para remover o pacote enviado.

PayU é uma marca registrada de seu respectivo proprietário. Esta extensão não é afiliada nem endossada pela PayU.