VibeFox Wompi 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 mais antigas do PHP.

Moeda: peso colombiano (COP). A Wompi Colombia cobra em COP, e o método de pagamento fica oculto para carrinhos em outras moedas. A página de configuração avisa quando a moeda padrão da loja não é COP.

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 Wompi Panamá usam APIs diferentes e não têm suporte.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um 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, mais tarde, encontre VibeFox Wompi Payment na lista de módulos e clique em Configure.

3. Cole 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. Cole as chaves de sandbox e de produção do painel do comerciante Wompi e defina a URL de eventos na Wompi (veja Configuração).

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

Na instalação, o módulo cria dois status de pedido, Awaiting Wompi payment e Wompi payment on hold. O PrestaShop oferece um novo módulo de pagamento para as moedas, países e grupos de clientes que existem naquele momento. Verifique se COP está permitido em Payment > Preferences. Um país adicionado depois precisa ser marcado ali antes que os clientes desse país vejam a Wompi.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Wompi Payment > Configure. Cada seção com campos tem o próprio botão Save, que salva a página inteira. Acima dos campos, 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 preenchidas. Quando todas as chaves estão preenchidas, ela informa se pagamentos reais serão cobrados. Ao salvar, o módulo 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.

Wompi

Enable/Disable: Enable Wompi liga ou desliga o método de pagamento. Padrão: off.

Title: o nome do método de pagamento que os clientes veem no checkout. Também é o nome do método de pagamento salvo no pedido. Padrão: Wompi. Se você deixar vazio, o nome do módulo será usado.

Description: o texto exibido abaixo do método de pagamento no checkout. 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: 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: on. Desative para aceitar pagamentos reais. Enquanto estiver ativo, os clientes veem Modo sandbox: nenhum pagamento real é feito. abaixo do método de pagamento.

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 de sandbox (pub_test_...). Ela identifica sua conta no Wompi Web Checkout.

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

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

Integrity secret: o segredo de integridade de 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 aparecem nos seus campos. As chaves privadas e os segredos salvos nunca são exibidos novamente. O campo fica vazio e mostra Salvo: deixe vazio para mantê-lo. Digite um valor novo somente se quiser alterá-lo.

Clear saved secrets: marque uma chave privada ou um segredo de qualquer um dos ambientes e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

URL de eventos (webhook)

Os eventos da Wompi informam à sua loja que uma transação mudou. No painel do comerciante Wompi, seção de desenvolvedores, defina a URL de eventos exibida nesta seção, para o sandbox e para a produção. Com URLs amigáveis, ela tem este formato https://your-shop/module/wcp_wompi_payment/webhook, possivelmente com um código de idioma como /es/. Copie a URL exatamente como as configurações a mostram.

O módulo usa este evento:

Os demais 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 URL de eventos, o pedido só é criado quando o cliente volta à loja depois de pagar.

Avançado

Debug log: grava a atividade de pagamentos e webhooks em logs/wompi_p_debug.log.php, na pasta do módulo. 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: off.

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

Delete data on uninstall: quando ativo, desinstalar o módulo remove as configurações do módulo e o log. As tentativas de pagamento da Wompi e os status de pedido do módulo sempre permanecem, para que os pedidos existentes mantenham seus dados da Wompi. Padrão: off.

Checkout

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Wompi) e confirma. O módulo cria uma tentativa de pagamento com referência própria (PS-, o número do carrinho 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 carrinho em COP. O e-mail do cliente e o nome do endereço de cobrança são enviados à Wompi. Nenhum pedido existe ainda nesse ponto.

Na página da Wompi, o cliente paga com qualquer método de pagamento ativado na sua conta Wompi. Em seguida, a Wompi devolve o cliente à sua loja. O pedido só é marcado como pago depois que a Wompi confirma: por meio de um evento assinado ou de uma solicitação no 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 carrinho no ambiente da tentativa são aceitas. Ao recarregar a página, a transação é verificada novamente no máximo uma vez a cada 20 segundos.

Quando a transação é aprovada, o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Para um pagamento pendente (por exemplo, PSE, Nequi ou pagamento em dinheiro), a página mostra Seu pagamento Wompi está aguardando confirmação (por exemplo, PSE, Nequi ou pagamento em dinheiro). Processaremos o pedido assim que a Wompi confirmar o pagamento. Para um pedido em espera, mostra Recebemos seu pagamento Wompi e estamos analisando. Entraremos em contato se for necessário algo. Se um pagamento pendente for recusado depois, a página mostra Seu pagamento Wompi não foi aprovado. Entre em contato conosco. Se for anulado, a página mostra Seu pagamento Wompi foi anulado e este pedido foi cancelado. Entre em contato conosco.

Se a Wompi ainda não tiver confirmado a transação quando o cliente retornar, aparece uma página com Estamos aguardando a Wompi confirmar seu pagamento. Você receberá um e-mail assim que ele for confirmado. e um botão Check again. O evento da Wompi cria o pedido assim que chega.

Se o pagamento for recusado, nenhum pedido é criado e o carrinho é mantido. O cliente volta ao checkout com Seu pagamento Wompi não foi aprovado (...). Você pode tentar novamente ou escolher outro método de pagamento., com o motivo informado pela Wompi. Um pagamento anulado exibe Seu pagamento Wompi foi anulado. Você pode tentar novamente ou escolher outro método de pagamento. Se o cliente sair do Web Checkout sem pagar, a mensagem é Seu pagamento Wompi não foi concluído. Você pode tentar novamente ou escolher outro método de pagamento. Cada nova tentativa recebe uma nova referência. Depois que o carrinho tem um pedido (pago, pendente, Erro de pagamento ou Cancelado), ele não pode ser pago novamente: o cliente é levado à página de confirmação do pedido.

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 carrinho é COP e permitida para o módulo, e o total é de pelo menos COP 1.500. Se o pagamento não puder começar, o cliente permanece no checkout com uma mensagem curta:

A URL de eventos funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.

O módulo não faz reembolsos pelo PrestaShop. 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

Nenhum pedido ainda: o cliente foi enviado à Wompi e não pagou, o pagamento foi recusado ou a Wompi ainda não confirmou a transação. Existe apenas o carrinho.

Awaiting Wompi payment: a Wompi informa a transação como pendente, por exemplo pagamentos PSE, Nequi ou em dinheiro aguardando confirmação. O pedido espera até que a Wompi o aprove ou recuse. Quando aprovado, o pagamento é registrado e o pedido passa para Payment accepted.

Payment accepted: a transação foi aprovada pelo valor do carrinho em COP. O pagamento é registrado com o ID da transação Wompi, e uma nota mostra a transação, o tipo de método de pagamento (por exemplo CARD, PSE ou NEQUI), a referência, o valor e o ambiente.

Wompi payment on hold: 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 nota explica o motivo. Confira o pagamento no painel da Wompi e então processe o pedido ou reembolse o pagamento.

Payment error: uma transação pendente da última tentativa de pagamento foi recusada ou terminou com erro. A mensagem da Wompi é adicionada à nota. Os resultados de tentativas anteriores não alteram o pedido.

Canceled: uma transação pendente da última tentativa de pagamento foi anulada na Wompi.

Se chegar um segundo pagamento aprovado para um pedido que já está pago, o pedido não muda. 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 de um pedido reembolsado apenas acrescenta uma nota. Eventos e retornos repetidos nunca duplicam notas, e-mails ou pagamentos.

Bloco de pagamento Wompi

A página do pedido mostra um bloco Wompi payment com a referência, o ID da transação, o status (com o status da Wompi), o valor solicitado, o valor da transação, o método de pagamento, a mensagem da Wompi, um selo SANDBOX para pagamentos de sandbox, as Payment attempts do carrinho quando houve várias, e as Wompi notes do pedido.

Reembolsos

Os reembolsos não são enviados pelo PrestaShop. Reembolse ou anule o pagamento no painel do comerciante Wompi e depois registre o reembolso manualmente no PrestaShop. Uma anulação da transação de pagamento feita na Wompi é adicionada ao pedido como nota.

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 Wompi Payment é o primeiro bloco de Modules > Module Manager > VibeFox Wompi Payment > Configure, 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 estão a linha Product: presta-payment-wompi e o link Manage licenses and domains in your account, que abre sua conta vibefox.net. Somente 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 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 Wompi não é exibida aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A vitrine 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 no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados pelos eventos da Wompi e quando o cliente retorna.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado novamente automaticamente enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser informada, 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 Wompi não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ligado e se 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 carrinho é COP e se o total é de pelo menos COP 1.500. Em Payment > Preferences, verifique se o módulo está permitido para COP, para o país do cliente e para o grupo do cliente.

O pagamento foi concluído, mas nenhum pedido foi criado: a URL de eventos não está funcionando. No painel da Wompi, verifique se a URL de eventos está definida para o ambiente que você usa (sandbox ou produção) e se é exatamente a que aparece nas configurações. Verifique se o segredo de eventos desse ambiente está na seção correspondente. O pedido também é criado quando o cliente volta à loja depois de pagar.

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

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

A URL de eventos 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 reenviará o evento mais tarde.

A URL de eventos responde Retry: o pedido estava sendo confirmado por outra solicitação no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Wompi reenviará o evento mais tarde. Veja o campo Log para o motivo.

A URL de eventos 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.

A URL de eventos responde Unknown reference: a referência da transação não foi emitida por esta loja, por exemplo porque a mesma conta Wompi é usada por outra loja. Referências de outros sistemas recebem a resposta Ignored.

A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas solicitações da Wompi.

Aviso ao salvar de que a chave não começa com ...: uma chave foi colada na seção errada. Chaves de sandbox começam com pub_test_, prv_test_, test_events_ e test_integrity_; chaves de produção começam com pub_prod_, prv_prod_, prod_events_ e prod_integrity_.

O pedido está em Wompi payment on hold: leia as notas no bloco Wompi payment (veja Status do pedido) e depois processe o pedido ou reembolse o pagamento no painel da Wompi.

Outros erros: veja o campo Log na página do módulo e as Wompi notes do pedido. Os erros são sempre registrados. Ative o Debug log para mais detalhes.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Wompi 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 on uninstall estiver ativo, as configurações do módulo 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 da Wompi e os status de pedido Awaiting Wompi payment e Wompi payment on hold são sempre mantidos, para que um evento tardio de um pagamento antigo ainda seja reconhecido após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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