VibeFox Wompi for OpenCart — Ajuda

Requisitos

OpenCart: 3.0.x (testado na 3.0.5.0) ou 4.0.2 e superior (testado na 4.1.0.3).

PHP: 8.0 ou superior.

Moeda: peso colombiano (COP). A Wompi Colômbia cobra em COP. Adicione o COP em System > Localisation > Currencies se a sua loja ainda não o tiver; o método de pagamento só é oferecido quando o cliente finaliza a compra em COP. A página de configurações avisa quando a moeda padrão da loja não é COP.

Conta Wompi: uma conta de comerciante da Wompi Colômbia. Cada ambiente (sandbox e produção) tem quatro chaves: chave pública, chave privada, segredo de eventos e segredo de integridade. Você as encontra no painel do comerciante Wompi (comercios.wompi.co), na seção de desenvolvedores. A Wompi El Salvador e o Panamá usam APIs diferentes e não são suportados.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 para o OpenCart 3 wcp_wompi_payment-oc3-(version).ocmod.zip e o pacote para o OpenCart 4 wcp_wompi_payment.ocmod.zip. Instale somente 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, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_wompi_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ê também pode copiar o conteúdo da pasta upload deste pacote para a pasta raiz da sua loja.

2. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Wompi Payment e clique em Install (o botão verde +). Seu usuário administrador precisa ter permissão para modificar a lista de extensões de pagamento.

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

4. Cole as chaves de sandbox e de produção do painel do comerciante Wompi e defina a Events URL na Wompi (veja Configuração).

5. Ative Enable/Disable e clique em Save. Teste um pagamento no modo sandbox e depois desative Sandbox mode para aceitar pagamentos reais.

OpenCart 4

1. No admin, vá em Extensions > Installer, clique em Upload e escolha o arquivo wcp_wompi_payment.ocmod.zip. Não renomeie o arquivo: o OpenCart 4 obtém o código da extensão 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. Vá em Extensions > Extensions e escolha o tipo Payments. Encontre VibeFox Wompi Payment, clique em Install (o botão verde +) e depois em Edit (o botão de lápis).

4. Informe a chave de licença, as chaves da Wompi e a Events URL como nos passos 3 a 5 para o OpenCart 3. A página de configurações e os seus campos são iguais nas duas versões. Só a Events URL é diferente (veja Events URL).

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

Configuração

Todas as configurações estão na página da extensão: Extensions > Extensions > Payments > VibeFox Wompi Payment > Edit. As seções são listadas à esquerda; o botão Save abaixo da lista salva a página inteira. Acima das configurações, uma caixa de status mostra o modo atual, SANDBOX ou PRODUCTION. Quando falta uma chave desse modo, a caixa a lista e informa que o método de pagamento fica oculto no checkout até que todas as chaves desse ambiente sejam definidas. Quando todas as chaves estão definidas, ela informa se pagamentos reais serão cobrados. Ao salvar, a extensão avisa se uma chave não começa com o prefixo da sua seção e se a Wompi está ativada, mas oculta no checkout por falta de chaves. Title deve ter no máximo 128 caracteres (Title must be at most 128 characters.), Sort Order deve ser um número inteiro (Sort Order must be a whole number.), Total deve ser um número igual ou maior que 0 (Total: enter a number, 0 or greater.), e a zona geográfica e os status de pedido selecionados devem existir; caso contrário, nada é salvo e a página mostra o erro. Sem a permissão para modificar a extensão, a página mostra as configurações, mas não consegue salvá-las.

Wompi

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

Title: o nome do método de pagamento que os clientes veem no checkout. É também o nome do método de pagamento armazenado no pedido. Padrão: Wompi. No máximo 128 caracteres. Se você deixar em branco, o nome da extensão será usado.

Description: o texto mostrado ao cliente na etapa Confirm Order, acima do botão de confirmação. Padrão: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

Sort Order: a posição da Wompi entre os métodos de pagamento no checkout. Deixe em branco ou digite um número inteiro; números negativos são permitidos.

Geo Zone: oferece a Wompi somente 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. No OpenCart 4, quando o checkout não tem endereço de pagamento, o endereço de entrega é verificado.

Total: o total do checkout, na moeda padrão da loja, que um pedido precisa atingir para que a Wompi seja oferecida: um número igual ou maior que 0. Deixe em branco para oferecê-la para qualquer total. A própria Wompi exige no mínimo COP 1,500.

Conta Wompi

Copie as chaves do painel do comerciante Wompi (comercios.wompi.co), seção de desenvolvedores. Cada ambiente tem sua própria chave pública, chave privada, segredo de eventos e segredo de integridade.

Sandbox mode: usa o sandbox da Wompi (chaves de sandbox, sem dinheiro real). Ele troca tanto as chaves quanto a API da Wompi (sandbox.wompi.co ou production.wompi.co). As tentativas de pagamento mantêm o ambiente em que foram feitas. Padrão: ativado. Desative para aceitar pagamentos reais. Enquanto estiver ativado, os clientes veem Sandbox mode: no real payment is made. na etapa Confirm Order.

Chaves de sandbox

As quatro chaves do sandbox da Wompi. Elas começam com pub_test_, prv_test_, test_events_ e test_integrity_.

Public key: a chave pública do sandbox (pub_test_...). Ela identifica sua conta no Wompi Web Checkout.

Private key: a chave privada do sandbox (prv_test_...). Ela é usada para ler transações da API da Wompi.

Events secret: o segredo de eventos do sandbox (test_events_...). Ele verifica a assinatura dos eventos da Wompi.

Integrity secret: o segredo de integridade do sandbox (test_integrity_...). Ele assina a solicitação de pagamento enviada ao Web Checkout.

Chaves de produção

As quatro chaves do ambiente de produção da Wompi. Elas começam com pub_prod_, prv_prod_, prod_events_ e prod_integrity_.

Public key: a chave pública de produção (pub_prod_...).

Private key: a chave privada de produção (prv_prod_...).

Events secret: o segredo de eventos de produção (prod_events_...).

Integrity secret: o segredo de integridade de produção (prod_integrity_...).

As chaves públicas são exibidas nos seus campos. Chaves privadas e segredos salvos nunca são mostrados novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo. Para remover um valor salvo, marque Clear saved secret on save abaixo do campo e clique em Save.

Events URL (webhook)

Os eventos da Wompi informam sua loja de que uma transação mudou. No painel do comerciante Wompi, na seção de desenvolvedores, defina a Events URL mostrada nesta seção, para o sandbox e para a produção. Ela é montada a partir do endereço da vitrine da sua instalação do OpenCart. No OpenCart 3 ela tem este formato: https://your-store/index.php?route=extension/payment/wcp_wompi_payment/webhook, e no OpenCart 4: https://your-store/index.php?route=extension/wcp_wompi_payment/payment/wcp_wompi_payment.webhook. Copie a URL exatamente como as configurações a mostram.

A extensão usa este evento:

Os outros eventos recebem a resposta Ignored. Cada evento é verificado com o segredo de eventos do seu ambiente (sandbox ou produção). Webhooks sem assinatura válida são rejeitados. Após a verificação, a transação é lida da API da Wompi com a chave privada desse ambiente, e somente esses dados são usados. Sem a Events URL, um pedido só recebe seu status quando o cliente volta à loja depois de pagar.

Pedidos

O OpenCart cria o pedido na etapa Confirm Order sem status (um pedido ausente). Ele só recebe um status quando a Wompi informa a transação. Cada campo abaixo lista os seus status de pedido do OpenCart.

Order Status After Payment: uma transação APPROVED com o valor esperado em COP. Padrão: Processing.

Awaiting Payment Status: uma transação PENDING, por exemplo PSE, Nequi ou um pagamento em dinheiro aguardando confirmação. O pedido recebe Order Status After Payment quando a Wompi o aprova. Padrão: Pending.

On Hold (Review) Status: a Wompi aprovou um valor ou uma moeda diferentes do total do pedido, ou aprovou o pagamento depois que o pedido havia sido cancelado. Uma observação explica isso; o pedido não é marcado como pago. Padrão: Pending, porque o OpenCart não tem o status On hold. Você pode criar seus próprios status em System > Localisation > Order Statuses e selecioná-los aqui.

Failed Payment Status: uma transação pendente da última tentativa de pagamento foi recusada ou terminou com erro. Padrão: Failed.

Cancelled Order Status: uma transação pendente da última tentativa de pagamento foi cancelada na Wompi. Um pagamento aprovado para um pedido neste status o coloca em espera em vez de marcá-lo como pago. Padrão: Canceled.

Avançado

Debug log: grava a atividade de pagamentos e webhooks no arquivo wompi_p_debug.log.php, na pasta de logs do OpenCart (storage/logs; no OpenCart 4, system/storage/logs). O arquivo não pode ser aberto pela web. Erros e avisos são sempre registrados, mesmo quando esta opção está desativada. Chaves, segredos e dados de clientes nunca são registrados. Padrão: desativado.

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

Delete data on uninstall: quando ativado, desinstalar a extensão remove as configurações da extensão e o log. Pedidos e tentativas de pagamento da Wompi são sempre mantidos. Padrão: desativado.

Import / Export

Export: Download JSON salva as configurações em um arquivo JSON. Chaves privadas e segredos não são exportados.

Import: cole um JSON exportado anteriormente e clique em Import para restaurar as configurações. As chaves privadas e os segredos salvos são mantidos.

Finalização de compra

Na etapa Payment Method, o cliente escolhe o método de pagamento (por padrão, Wompi). Na etapa Confirm Order, o cliente vê a sua descrição. O OpenCart cria o pedido nesta etapa, ainda sem status. Quando o cliente clica em Confirm Order, a extensão cria uma tentativa de pagamento com referência própria (OC-, o número do pedido e um carimbo de data e hora), assina a solicitação com o segredo de integridade e envia o cliente ao Wompi Web Checkout com o total do pedido em COP. O e-mail do cliente e o nome do endereço de pagamento são repassados à Wompi. No OpenCart 4 o cliente escolhe o método de pagamento com o botão Choose do bloco do método de pagamento, na janela Payment method options, e clica em Confirm Order na parte de baixo da página de finalização da compra. Se a finalização não tiver um endereço de pagamento, o nome é tirado do pedido ou do endereço de entrega.

Na página da Wompi, o cliente paga com qualquer método de pagamento ativado na sua conta Wompi. Depois, a Wompi devolve o cliente à sua loja. O pedido só é marcado como pago depois que a Wompi confirma: por um evento assinado ou por uma solicitação feita pelo servidor à API da Wompi quando o cliente retorna. O número da transação no próprio endereço de retorno não é considerado confiável, e somente transações criadas para aquele pedido no ambiente da sua tentativa são aceitas. Em recarregamentos da página, a transação é verificada novamente no máximo uma vez a cada 20 segundos.

Quando a transação é aprovada, o pedido recebe seu status da forma padrão do OpenCart, com os e-mails de pedido habituais e a atualização do estoque, e o cliente vê a página de sucesso do pedido do OpenCart. Para um pagamento pendente (por exemplo PSE, Nequi ou um pagamento em dinheiro), a página mostra Your Wompi payment is pending confirmation (for example PSE, Nequi or a cash payment). We will process the order as soon as Wompi confirms the payment. Para um pedido em análise, mostra We have received your Wompi payment and are reviewing it. We will contact you if anything is needed. Se um pagamento pendente for recusado depois, a página mostra Your Wompi payment was not approved. Please contact us. Se for cancelado, a página mostra Your Wompi payment was voided and this order was cancelled. Please contact us.

Se a Wompi ainda não tiver confirmado a transação quando o cliente retorna, uma página mostra We are waiting for Wompi to confirm your payment. You will receive an e-mail as soon as it is confirmed. com os botões Check again e Back to checkout. O evento da Wompi define o status do pedido assim que chega.

Se o pagamento for recusado, o pedido continua sem status e o carrinho é mantido. O cliente volta ao checkout com Your Wompi payment was not approved (...). You can try again or choose another payment method., com o motivo informado pela Wompi. Um pagamento cancelado mostra Your Wompi payment was voided. You can try again or choose another payment method. Se o cliente sair do Web Checkout sem pagar, a mensagem é Your Wompi payment was not completed. You can try again or choose another payment method. Cada nova tentativa recebe uma nova referência. O OpenCart cria um novo pedido sempre que a etapa Confirm Order é exibida, mas um carrinho é pago somente uma vez: quando um pedido do carrinho está pago, aguardando pagamento ou em análise, o cliente é levado à página de sucesso em vez de pagar de novo.

No OpenCart 4 essas mensagens são exibidas acima da página de finalização da compra. O OpenCart 4 mantém um único pedido para a finalização da compra e o atualiza sempre que o passo Confirm Order é exibido: após um pagamento recusado ou não concluído, o cliente paga o mesmo pedido com uma nova tentativa. Se esse pedido tiver sido fechado sem pagamento nesse meio-tempo (por exemplo, o pagamento PSE ou Nequi pendente foi recusado ou cancelado depois, ou você o cancelou), ou se o carrinho tiver sido alterado depois que um pagamento começou, o pedido sai da finalização da compra e o cliente vê Your previous order is already closed or paid. Please confirm the order again: the cart will be paid with a new order. O próximo Confirm Order paga o carrinho com um novo pedido.

O método de pagamento só é exibido quando a licença está ativa, todas as quatro chaves do modo atual estão definidas, o cliente finaliza a compra em COP e o total é de pelo menos COP 1,500. Se o pagamento não puder começar, o cliente permanece na etapa Confirm Order com uma breve mensagem acima do botão:

A Events URL também funciona enquanto a loja está em modo de manutenção, porque o OpenCart deixa passar as requisições das extensões de pagamento. No OpenCart 4, uma ação de inicialização da extensão deixa passar a Events URL e o retorno do cliente.

A extensão não faz reembolsos pelo OpenCart. Não há cartões salvos, assinaturas nem campos de cartão no seu site: todos os dados de pagamento são digitados na Wompi.

Pedidos

Status de pedido

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

Awaiting Payment Status (padrão Pending): a Wompi informa a transação como pendente, por exemplo pagamentos PSE, Nequi ou em dinheiro aguardando confirmação. O pedido aguarda até que a Wompi aprove ou recuse. Quando é aprovado, o pedido passa para Order Status After Payment.

Order Status After Payment (padrão Processing): a transação foi aprovada pelo valor do pedido em COP. Uma observação mostra a transação, o tipo do método de pagamento (por exemplo CARD, PSE ou NEQUI), a referência, o valor e o ambiente.

On Hold (Review) Status (padrão Pending): a Wompi aprovou um valor ou uma moeda diferentes do total do pedido (por exemplo, o carrinho foi alterado depois que o pagamento começou), ou o pagamento foi aprovado depois que o pedido havia sido cancelado. O pedido não é marcado como pago. A observação explica isso. Verifique o pagamento no painel da Wompi e depois atenda o pedido ou reembolse o pagamento.

Failed Payment Status (padrão Failed): uma transação pendente da última tentativa de pagamento foi recusada ou terminou com erro. A mensagem da Wompi é adicionada à observação. Resultados de tentativas anteriores não alteram o pedido.

Cancelled Order Status (padrão Canceled): uma transação pendente da última tentativa de pagamento foi cancelada na Wompi.

Quando um pedido que já tem um status muda (por exemplo, de aguardando para pago ou falhou), o OpenCart notifica o cliente. Se chegar um segundo pagamento aprovado para um pedido já pago, ou para outro pedido de um carrinho já pago, o pedido não é alterado. Uma observação pede que você reembolse o pagamento duplicado no painel da Wompi. Se a transação de pagamento for cancelada na Wompi, uma observação pede que você revise o pedido. Eventos e retornos repetidos nunca duplicam observações ou pagamentos.

As observações são entradas do History do pedido que o cliente não vê.

Aba VibeFox Wompi Payment

Em Sales > Orders, abra um pedido pago com a Wompi. Na parte inferior da página do pedido, ao lado de History e Additional, a aba VibeFox Wompi Payment mostra a Reference, o Transaction ID, o Status (com o status da Wompi), o valor Requested, o Transaction amount, o Payment method, a Wompi message, um rótulo SANDBOX para pagamentos de sandbox, as Payment attempts do carrinho quando houve várias e as Wompi notes do pedido. A aba é mostrada aos usuários que têm acesso à extensão.

Reembolsos

Os reembolsos não são enviados pelo OpenCart. Reembolse ou cancele o pagamento no painel do comerciante da Wompi e depois registre o reembolso no OpenCart manualmente. Um cancelamento da transação de pagamento feito na Wompi é adicionado ao pedido como observação. Devoluções de produtos em Sales > Returns não devolvem dinheiro pela Wompi.

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 Wompi Payment é o primeiro bloco da página Extensions > Extensions > Payments > VibeFox Wompi Payment > Edit, acima das configurações. Insira a chave em License key e clique em Activate. Depois, 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 ficam a linha Product: opencart-payment-wompi e o link Manage licenses and domains in your account, que abre a sua conta 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 administrador (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 com 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, a extensão continua funcionando com o último status conhecido.

Uma chave funciona em um único domínio: o endereço da loja nas configurações do OpenCart. Remover a chave da loja não libera a vaga do domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a Wompi não é mostrada aos clientes no checkout. Se mesmo assim um pagamento for iniciado, o cliente vê This payment method is not available. Please choose another one. Um usuário administrador que esteja conectado ao painel 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 administrador, por isso, sem uma chave ativa, o método de pagamento fica oculto para todos. Depois que você abrir a página Edit uma vez, aparece um lembrete no Dashboard do painel. Feche-o com × para ocultá-lo por 7 dias. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados pelos eventos da Wompi e pelos retornos dos clientes.

Quando uma licença expira, a extensão continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente de forma automática quando você abre o Dashboard do painel ou a página Edit: uma vez por dia nos primeiros 14 dias após a chave ser inserida, 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

A Wompi não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ativado e se todas as quatro chaves do modo atual estão definidas (a caixa de status na página de configurações lista as chaves faltantes). Verifique também se o cliente finaliza a compra em COP e se o total é de pelo menos COP 1,500. Confira ainda 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 Events URL não está funcionando. No painel da Wompi, verifique se a Events URL está definida para o ambiente que você usa (sandbox ou produção) e se é exatamente a mostrada nas configurações. Verifique se o segredo de eventos desse ambiente está na seção correspondente. O pedido também recebe o status quando o cliente volta à loja depois de pagar.

Events URL answers Not configured: o segredo de eventos do ambiente do evento está vazio. Cole-o nas configurações.

Events URL answers Invalid signature: o segredo de eventos pertence a outro ambiente ou a outra conta. Copie-o novamente do painel da Wompi.

Events URL answers Transaction lookup failed: a API da Wompi não retornou a transação, por exemplo por causa de uma chave privada errada ou de um problema de rede. A Wompi enviará o evento novamente mais tarde.

Events URL answers Retry: o pedido estava sendo confirmado por outra requisição no mesmo momento, ou o status do pedido não pôde ser definido. A Wompi enviará o evento novamente mais tarde. Veja o campo Log para o motivo.

Events URL answers Environment mismatch: uma transação de sandbox chegou para uma tentativa de pagamento de produção, ou o contrário. Pagamentos de sandbox nunca confirmam pedidos de produção.

Events URL answers Unknown reference: a referência da transação parece uma referência desta loja, mas nunca foi emitida aqui, por exemplo por outra loja OpenCart na mesma conta Wompi. Referências de outros sistemas recebem a resposta Ignored: not an OpenCart reference.

The Events URL shows Method not allowed in the browser: isso é normal. A URL aceita somente requisições da Wompi.

The key does not start with ... warning on save: uma chave foi colada na seção errada. Chaves de sandbox começam com pub_test_, prv_test_, test_events_ e test_integrity_; as de produção, com pub_prod_, prv_prod_, prod_events_ e prod_integrity_.

Order is in the review status: leia as observações na aba VibeFox Wompi Payment (veja Status de pedido) e depois atenda o pedido ou reembolse o pagamento no painel da Wompi.

Other errors: veja o campo Log na página da extensão e as Wompi notes do pedido. Erros são sempre registrados. Ative Debug log para mais detalhes.

Desinstalação

Vá em Extensions > Extensions, escolha o tipo Payments e clique em Uninstall (o botão vermelho −) ao lado de VibeFox Wompi 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 Events URL no modo de manutenção). Se Delete data on uninstall estiver ativado, as demais configurações (título, descrição, modo sandbox, chaves, registro) e o log são removidos. Se estiver desativado, elas são mantidas para uma reinstalação posterior. As tentativas de pagamento da Wompi são sempre mantidas, então um evento atrasado de um pagamento antigo ainda é reconhecido após uma reinstalação. Os pedidos existentes mantêm suas observações de pagamento.

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

Wompi é uma marca registrada de seu respectivo titular. Esta extensão não é afiliada nem endossada pela Wompi.