VibeFox Wompi for WooCommerce — Ajuda

Requisitos

WordPress: 5.8 ou superior.

WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Moeda da loja: peso colombiano (COP). A Wompi Colombia cobra em COP, e o método de pagamento fica oculto para pedidos em outras moedas.

Conta Wompi: uma conta de comerciante Wompi Colombia. 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 a Panamá usam APIs diferentes e não são compatíveis.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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_wompi_payment para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Defina a moeda da loja como peso colombiano (COP) em WooCommerce > Settings > General.

4. Abra as configurações: WooCommerce > Settings > Payments > Wompi, ou clique em Settings abaixo do nome do plugin na página Plugins.

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

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

7. Ative Enable/Disable. Teste um pagamento no modo sandbox e, em seguida, desmarque Sandbox mode para aceitar pagamentos reais.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Wompi. Acima dos campos, uma caixa de status mostra o modo atual, SANDBOX ou PRODUCTION. Quando uma chave deste modo está faltando, a caixa a lista e informa que o método de pagamento fica oculto no checkout até que todas as chaves deste ambiente sejam preenchidas. Quando todas as chaves estão preenchidas, ela informa se pagamentos reais serão cobrados. Ao salvar, o plugin avisa se uma chave não começa com o prefixo de sua seção e se a Wompi está ativada, mas oculta no checkout porque faltam chaves. Na lista de métodos de pagamento, a Wompi aparece como precisando de configuração até que o modo atual tenha as quatro chaves. As chaves da versão 1.0 são movidas automaticamente para a seção Sandbox ou Production correspondente na atualização.

Geral

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 na finalização de compra. Padrão: Wompi.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

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: Use the Wompi sandbox (sandbox keys, no real money). Ele troca tanto as chaves quanto a API da Wompi (sandbox.wompi.co ou production.wompi.co). Os pedidos mantêm o ambiente em que foram pagos. Padrão: ativado. Desmarque para aceitar pagamentos reais.

Chaves 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_...).

Events URL (webhook)

Os eventos da Wompi informam à sua loja que uma transação foi alterada. No painel do comerciante Wompi, seção de desenvolvedores, defina a Events URL exibida nesta seção das configurações, tanto para o sandbox quanto para a produção. Ela tem este formato: https://your-site/wc-api/wompi_p/. Copie a URL exatamente como as configurações a mostram.

O plugin usa este evento:

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

Avançado

Debug log: Log payment and webhook activity grava a atividade de pagamentos e eventos em WooCommerce > Status > Logs, origem wcp_wompi_payment. Os erros são sempre registrados, mesmo quando esta opção está desativada. Chaves, segredos e dados de clientes nunca são registrados. Padrão: desativado.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Desativar o plugin nunca apaga nada. Os dados dos pedidos são sempre mantidos. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Wompi) e faz o pedido. No modo sandbox, a finalização de compra exibe Sandbox mode: no real payment is made. abaixo da descrição. O plugin cria uma tentativa de pagamento com referência própria (WC-, o número do pedido e um carimbo de data/hora), assina-a com o segredo de integridade e envia o cliente ao Wompi Web Checkout com o total do pedido em COP. O e-mail de cobrança e o nome do cliente são enviados à Wompi. Uma nota no pedido registra o ambiente, a referência e o valor.

Na página da Wompi, o cliente paga com qualquer método de pagamento ativado na sua conta Wompi. Depois, a Wompi envia o cliente de volta à página de pedido recebido da 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 chega a essa página. O número da transação no próprio endereço de retorno não é considerado confiável. A cada recarregamento da página, a transação é verificada novamente no máximo uma vez a cada 20 segundos.

Somente transações criadas para aquele pedido podem pagá-lo, e somente no ambiente da tentativa. Um cliente pode pagar novamente um pedido não pago, por exemplo pela página Pay for order. Cada tentativa recebe uma nova referência.

O método de pagamento só é exibido quando a licença está ativa, as quatro chaves do modo atual estão preenchidas, a moeda do pedido é COP e o total é de pelo menos COP 1.500. Se o pagamento não puder ser iniciado, o cliente vê uma mensagem curta e pode escolher outro método de pagamento:

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 o WooCommerce High-Performance Order Storage (HPOS). Traduções em espanhol para Colômbia e Espanha estão incluídas.

O plugin não faz reembolsos pelo WooCommerce. 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 do pedido

Pending payment: o cliente foi enviado à Wompi e ainda não pagou, ou a Wompi ainda não confirmou a transação.

On hold (pending payment): a Wompi informa a transação como pendente, por exemplo pagamentos PSE, Nequi ou em dinheiro aguardando confirmação. O pedido permanece em espera até que a Wompi o aprove ou recuse.

Processing or Completed: a transação foi aprovada. Aplica-se o padrão do WooCommerce: Processando, ou Concluído para pedidos com apenas produtos virtuais para download. A nota do pedido mostra a transação da Wompi, o tipo de método de pagamento (por exemplo cartão, PSE ou Nequi) e a referência. O ID da transação do pedido é o ID da transação da Wompi.

On hold after payment: a Wompi aprovou um valor ou uma moeda diferentes do total do pedido (por exemplo, o pedido foi editado 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 nota do pedido explica isso. Verifique o pagamento no painel da Wompi e conclua o pedido ou reembolse o pagamento.

Failed: a transação da última tentativa de pagamento foi recusada ou terminou com erro. A mensagem da Wompi é adicionada à nota. Resultados de tentativas anteriores não alteram o pedido.

Cancelled: a transação da última tentativa de pagamento foi anulada na Wompi antes de o pedido ser pago.

Se um segundo pagamento aprovado chegar para um pedido já pago, o pedido não é alterado. Uma nota pede que você reembolse a duplicata no painel da Wompi. Se a transação de pagamento for anulada na Wompi, uma nota pede que você revise o pedido. Um pagamento tardio para um pedido reembolsado apenas adiciona uma nota. Eventos repetidos e retornos de clientes nunca duplicam notas, e-mails ou alterações de estoque.

Reembolsos

Os reembolsos não são enviados pelo WooCommerce. Reembolse ou anule o pagamento no painel do comerciante Wompi e, em seguida, registre um reembolso manual no WooCommerce. Uma anulação feita na Wompi é adicionada ao pedido como nota.

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 > Wompi. 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 o 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 a sua conta na vibefox.net.

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

Sem uma chave ativa, a Wompi não é exibida 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. Os gerentes da loja conectados continuam vendo o método de pagamento, marcado como (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 Plugins e nas páginas do WooCommerce. Pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados por eventos da Wompi e pelos retornos dos clientes.

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

A Wompi 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 (a caixa de status na página de configurações lista as chaves que faltam). Verifique também se a moeda do pedido é COP e se o total é de pelo menos COP 1.500.

O pagamento foi feito, mas o pedido continua em Pending payment: 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 exibida nas configurações. Verifique se o segredo de eventos desse ambiente está na seção correspondente. O pedido também é confirmado quando o cliente volta à loja depois de pagar.

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

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

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

A Events URL responde Busy, retry: o pedido estava sendo atualizado por outra solicitação no mesmo momento. A Wompi enviará o evento novamente mais tarde.

A Events URL responde 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.

Aviso ao salvar «The key does not start with ...»: uma chave foi colada na seção errada. As 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_.

O pedido está On hold com uma nota sobre o valor: o valor ou a moeda aprovados diferem do total do pedido. Verifique o pagamento no painel da Wompi e conclua ou reembolse o pedido manualmente.

Outros erros: abra as notas do pedido ou WooCommerce > Status > Logs, origem wcp_wompi_payment. Os erros são sempre registrados. Ative o Debug log para mais detalhes. Desenvolvedores podem permitir outra moeda com o filtro wompi_p_supported_currencies, se a conta da Wompi aceitar.

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

Desinstalação

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

Wompi é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Wompi.