VibeFox Iugu for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. Sem o WooCommerce, o plugin não é ativado.

PHP: 8.0 ou superior.

Moeda da loja: real brasileiro (BRL). A Iugu cobra somente em BRL. O método de pagamento fica oculto quando a loja, ou o pedido na página Pay for order, usa outra moeda, e para valores abaixo de R$ 1,00 (o mínimo da Iugu).

Conta na Iugu: você precisa de dois tokens de API do painel da Iugu, um do tipo "Test" e outro do tipo "Live" (veja Configuração). A Iugu usa um único endereço de API para os dois: o token define se as faturas são de teste ou reais. Não é preciso configurar nenhum webhook na Iugu.

Chave de licença VibeFox: 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_iugu_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Defina a moeda da loja como real brasileiro (BRL) em WooCommerce > Settings > General.

4. Abra as configurações: WooCommerce > Settings > Payments > Iugu > Manage, 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. Insira os tokens de API de teste e de produção (veja Configuração), mantenha Test mode ativado, ative Enable / Disable e salve.

7. Faça um pedido de teste e pague com um cartão de teste da Iugu. Quando estiver pronto, desmarque Test mode.

Configuração

Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Iugu. Abaixo do título do gateway, a página mostra TEST MODE (as faturas são criadas com o token de API de teste, sem cobranças reais) ou LIVE. Ela avisa quando falta o token do modo ativo (nesse caso, o método de pagamento fica oculto na finalização de compra) e quando a moeda da loja não é BRL. Na lista de métodos de pagamento, a Iugu aparece como pendente de configuração até que o token do modo ativo seja inserido, e exibe um selo de modo de teste enquanto o modo de teste estiver ativo.

Geral

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

Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Iugu.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely via Iugu. You will be redirected to complete your payment.

Credenciais de API

Crie os tokens de API no Iugu Alia (alia.iugu.com): Settings > API integration > New. Crie um token do tipo "Test" e um do tipo "Live".

Test mode: Use the test API token (no real charges). Padrão: on. Enquanto o modo de teste estiver ativo, a finalização de compra exibe SANDBOX — Test mode enabled. No real charges. acima da descrição. Consultas de status e reembolsos de um pedido sempre usam o token do modo em que sua fatura foi criada, então trocar de modo não quebra pedidos antigos.

Test API token: o token de API da Iugu do tipo "Test". Usado enquanto o modo de teste estiver ativo.

Live API token: o token de API da Iugu do tipo "Live" (produção). Usado quando o modo de teste estiver desativado. Mantenha-o em segredo.

Notificações de pagamento

Cada fatura instrui a Iugu a informar mudanças de status à URL de notificação da sua loja, exibida nesta seção das configurações. Ela tem este formato: https://your-site/wc-api/webhook_wc_iugu/. Não há nada a configurar na Iugu. Um gatilho adicional de toda a conta (gatilho) apontando para a mesma URL é inofensivo. As notificações não contêm dados de pagamento em que a loja confia: a fatura é sempre consultada novamente na API da Iugu (status, valor, moeda) antes que o pedido seja alterado.

O plugin reage aos eventos da Iugu que podem alterar o status de uma fatura: invoice.status_changed, invoice.refund, invoice.released, invoice.dunning_action e invoices. Para cada um deles, ele lê a fatura e aplica o status dela:

Outros eventos e faturas que não pertencem a um pedido desta loja recebem a resposta OK e são ignorados. Sem notificações, um pedido só é verificado quando o cliente volta à loja a partir da página da Iugu.

Avançado

Debug log: Log API requests and notifications em WooCommerce > Status > Logs, origem wcp_iugu_gateway, sem tokens nem dados de clientes. Erros são sempre registrados. Padrão: off.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Padrão: off.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Iugu) e faz o pedido. É necessário um e-mail de cobrança válido. O plugin cria uma fatura da Iugu pelo total do pedido em BRL, com vencimento em 3 dias, e envia o cliente para a página da fatura na Iugu. Lá o cliente paga com cartão de crédito, boleto ou PIX, com os métodos ativados na sua conta Iugu. Nome e e-mail do cliente são enviados à Iugu, além de CPF/CNPJ, número do endereço e bairro dos campos do "Brazilian Market on WooCommerce" na finalização de compra, quando presentes. Telefone e endereço são enviados somente no formato aceito pela Iugu (telefones brasileiros e endereços brasileiros com CEP de 8 dígitos).

Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Iugu confirma: a fatura é consultada na API da Iugu quando o cliente retorna e quando a Iugu envia uma notificação. Se o cliente gerou um código de boleto ou PIX e voltou antes de pagar, o pedido fica Em espera até que a Iugu confirme o pagamento. O temporizador de pedidos não pagos do WooCommerce não cancela pedidos cuja fatura da Iugu ainda está aberta.

Se a fatura foi cancelada ou venceu e o pedido ainda pode ser pago, o cliente chega à página Pay for order com a mensagem The Iugu invoice was not paid (it was canceled or has expired). You can pay the order again below. Quando o cliente paga de novo, o plugin o direciona para a mesma fatura aberta, se o valor não tiver mudado. Caso contrário, cancela a fatura antiga na Iugu e cria uma nova, para que um pedido não possa ser pago duas vezes por meio de duas faturas abertas. Se uma fatura antiga for paga mesmo assim, o pagamento continua associado ao pedido.

Se a Iugu não conseguir criar a fatura, o cliente vê uma mensagem curta, por exemplo Iugu could not create the invoice: com o motivo e um pedido para verificar os dados de cobrança, ou Could not connect to Iugu. Please try again in a moment. O motivo técnico é adicionado às notas do pedido e ao log.

O método de pagamento funciona na finalização de compra clássica, no bloco Finalizar compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin aceita somente pagamentos únicos. Não há formulário de cartão no site, cartões salvos, assinaturas ou cobranças recorrentes, carnês, pagamentos divididos nem configurações de parcelamento: para parcelar, use as configurações da página da Iugu. Os métodos de pagamento oferecidos na página da Iugu não podem ser escolhidos nas configurações do plugin: são oferecidos todos os métodos ativados na sua conta Iugu.

Pedidos e reembolsos

Status do pedido

Pending payment: a fatura foi criada e o cliente ainda não pagou.

Processing or Completed: a Iugu confirmou o pagamento. O WooCommerce define o status habitual de um pedido pago. A nota do pedido mostra o ID da fatura da Iugu e o método de pagamento (cartão de crédito, boleto ou PIX). O ID da transação é o ID da fatura da Iugu e, na tela do pedido, leva à fatura na Iugu.

On hold: o cliente gerou um boleto ou PIX e voltou à loja (pagamento pendente), o pagamento com cartão está autorizado, mas ainda não capturado (capture na Iugu; o pedido é concluído quando a Iugu informa que a fatura foi paga), o pagamento está em análise, a fatura foi paga apenas parcialmente, foi aberta uma contestação (chargeback) ou o valor ou a moeda pagos não correspondiam ao pedido. Um pagamento que chega depois que o pedido foi cancelado também o deixa Em espera, em vez de reabri-lo silenciosamente. As notas do pedido indicam qual é o caso.

Failed: a fatura venceu sem pagamento. O cliente pode pagar o pedido novamente.

Cancelled: a fatura foi cancelada na Iugu.

Refunded: a fatura que pagou o pedido foi reembolsada na Iugu.

Se outra fatura do mesmo pedido também for paga, o pedido não é alterado novamente. Uma nota pede que você reembolse o pagamento duplicado na Iugu.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Iugu. O reembolso é enviado com o token do modo em que a fatura foi criada.

Somente faturas pagas podem ser reembolsadas, e não mais do que o valor ainda reembolsável na Iugu. Um reembolso só é considerado concluído quando a Iugu o confirma. Se a Iugu recusar o reembolso ou não o confirmar, o WooCommerce exibe o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com o ID da fatura e o motivo.

Um reembolso total feito no painel da Iugu marca o pedido como Reembolsado. Reembolsos parciais feitos no painel não são importados.

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 > Iugu. 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 em vibefox.net.

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

Sem uma chave ativa, a Iugu não é exibida 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. Gestores logados da loja 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, e os reembolsos funcionam.

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 Iugu não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ativado e se o token do modo ativo está configurado: Test API token no modo de teste, Live API token no modo real. A moeda da loja deve ser BRL e o total do pedido, de pelo menos R$ 1,00. A página de configurações mostra um aviso quando o token ou a moeda estão incorretos.

O pagamento foi feito, mas o pedido continua em Pending payment: a notificação da Iugu não chegou à sua loja ou não pôde ser verificada. Ative o Debug log e consulte WooCommerce > Status > Logs, origem wcp_iugu_gateway. Confirme que o seu site está acessível pela internet na URL de notificação exibida nas configurações e que o token do modo em que a fatura foi criada ainda está preenchido. O pedido também é verificado quando o cliente volta à loja após pagar.

Notification answers verification failed: a fatura não pôde ser consultada na API da Iugu naquele momento, por exemplo por causa de um erro de rede ou de um token incorreto. A Iugu tenta a notificação novamente.

Notification answers invalid invoice id: a notificação não tinha um ID de fatura válido. Nada é alterado.

Pedido em On hold: leia as notas do pedido. Um boleto ou PIX ainda não foi pago, um pagamento com cartão aguarda captura, o pagamento está em análise, parcialmente pago ou contestado, o valor pago não correspondeu ao pedido, ou o pagamento chegou depois que o pedido foi cancelado.

The customer sees "Iugu payments are not available right now": o token de API está ausente ou incorreto. Verifique o token do modo ativo.

O reembolso falha: leia a mensagem. Pagamentos por boleto não podem ser reembolsados pela Iugu, pagamentos por PIX só podem ser reembolsados integralmente, e somente faturas pagas podem ser reembolsadas. Se a Iugu não confirmou o reembolso, verifique a fatura na Iugu antes de tentar novamente.

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 em 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.

Desenvolvedores podem alterar a requisição da fatura, por exemplo limitar os métodos de pagamento com payable_with, pelo filtro wc_igu_invoice_data.

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 da licença deste plugin são sempre removidos. As configurações do gateway e os logs só são removidos se Delete Data on Uninstall estiver ativado. Caso contrário, permanecem para uma eventual reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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