VibeFox Iugu 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 anteriores do PHP.
Moeda: real brasileiro (BRL). A Iugu cobra somente em BRL. O método de pagamento fica oculto para carrinhos em outra moeda e para totais 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 é necessário 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 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 encontre depois o VibeFox Iugu Gateway na lista de módulos e clique em Configure.
3. Insira sua chave de licença VibeFox no campo License key do bloco de licença no topo da página de configuração e clique em Activate (veja Chave de licença).
4. Insira os tokens de API de teste e de produção (veja Configuração), mantenha Test mode ativado, ative Enable / Disable e clique em Save.
5. Faça um pedido de teste e pague-o na página da Iugu com um pagamento de teste da Iugu. Quando estiver pronto, desative Test mode.
Ao ser instalado, o módulo cria dois status de pedido: Awaiting Iugu payment e Iugu payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences. A Iugu só é oferecida para carrinhos em BRL, em qualquer caso.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Iugu Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, 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 no checkout) e quando a moeda padrão da loja não é BRL (nesse caso a Iugu não é oferecida para carrinhos em outras moedas).
Iugu
Enable / Disable: Enable Iugu payments liga ou desliga o método de pagamento. Padrão: off.
Title: o nome do método de pagamento que o cliente vê no checkout. Também é o nome do método de pagamento salvo no pedido. Padrão: Iugu. Obrigatório.
Description: o texto exibido abaixo do método de pagamento no checkout. 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: usa o token de API de teste, portanto nenhuma cobrança real é feita. Padrão: on. Enquanto o modo de teste estiver ativo, o checkout mostra SANDBOX — Test mode enabled. No real charges. acima da descrição. As consultas de status e os reembolsos de um pedido sempre usam o token do modo em que a fatura dele 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 está desativado. Mantenha-o em sigilo.
Os tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-lo.
Clear saved tokens: marque um token e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
Notificações de pagamento
Notification URL: cada fatura instrui a Iugu a informar as mudanças de status para esta URL da sua loja. Com URLs amigáveis, ela fica assim: https://your-shop/module/wcp_iugu_gateway/webhook. Não há nada a configurar na Iugu. Um gatilho (gatilho) adicional em nível de conta apontando para a mesma URL é inofensivo. As notificações não trazem dados de pagamento nos quais a loja confia: a fatura é sempre consultada novamente na API da Iugu (status, valor, moeda) antes que um pedido seja criado ou alterado.
O módulo 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 foram criados pela sua loja recebem resposta HTTP 200 e são ignorados, sem nenhuma requisição à Iugu. Sem notificações, uma fatura só é verificada quando o cliente volta à loja a partir da página da Iugu.
Avançado
Debug log: grava as requisições e notificações da Iugu em logs/wc_igu_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Tokens e dados de clientes não são registrados. Erros e avisos são sempre gravados, mesmo com a chave desligada. Padrão: off.
Log: mostra o tamanho e os últimos registros do log. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ativado, desinstalar o módulo remove as configurações do gateway e o log. Pedidos, referências das faturas da Iugu, reembolsos e os status de pedido do módulo são sempre mantidos, de modo que os pedidos antigos continuam funcionando após uma reinstalação. Padrão: off.
Checkout
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Iugu) e confirma. É necessário um e-mail válido do cliente. O módulo cria uma fatura na Iugu pelo total do carrinho 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. A fatura mostra Order # e o número do carrinho. O nome e o e-mail do cliente são enviados à Iugu, além da empresa e do CPF/CNPJ do campo Identification number ou VAT number do endereço, quando presentes. Telefone e endereço são enviados somente no formato que a Iugu aceita (telefones brasileiros, endereços brasileiros com CEP de 8 dígitos; o número do imóvel é enviado como s/n). Nesse ponto ainda não existe pedido.
Depois de pagar, o cliente retorna à 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. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido com Your payment with Iugu has been received.
Se o cliente gerou um código de boleto ou PIX e voltou antes de pagar, o pedido é criado em Awaiting Iugu payment e a página de confirmação mostra Your Iugu invoice is awaiting payment (boleto / PIX). The order will be confirmed as soon as Iugu reports the payment. O pedido passa para Payment accepted quando a Iugu informa o recebimento, por notificação ou quando o cliente abre novamente o link de retorno. Se a Iugu ainda não puder ser contatada quando o cliente voltar, uma página Payment confirmation mostra We are confirming your payment with Iugu. The order will be updated automatically — please do not pay again. com um botão Check again e um botão Back to checkout. Um pedido cuja fatura foi cancelada ou venceu sem pagamento mostra Your Iugu payment was not completed. Please contact us about this order. na página de confirmação.
Se a fatura foi cancelada ou venceu antes que exista um pedido, o cliente volta ao checkout com The Iugu invoice was not paid (it was canceled or has expired). You can pay again below. O carrinho é mantido. Quando o cliente paga novamente, o módulo o envia para a mesma fatura aberta, desde que o valor e o modo não tenham mudado. Caso contrário, ele cancela a fatura antiga na Iugu e cria uma nova, para que um mesmo carrinho não possa ser pago por meio de duas faturas abertas. Se uma fatura antiga for paga mesmo assim, o pagamento continua associado ao carrinho.
Se a Iugu não conseguir criar a fatura, o cliente permanece no checkout com 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 é gravado no log.
A URL de notificação 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 aceita apenas 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: use as configurações da página da Iugu para parcelamentos. Os métodos de pagamento oferecidos na página da Iugu não podem ser escolhidos nas configurações do módulo: são oferecidos todos os métodos ativados na sua conta Iugu. Um pedido em Payment error ou Canceled não pode ser pago novamente pela loja; o cliente faz um novo pedido.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à Iugu e ainda não pagou, ou a Iugu ainda não confirmou o pagamento. Só existe o carrinho.
Payment accepted: a Iugu confirmou o pagamento. O pagamento é registrado com o ID da fatura da Iugu como ID da transação, e uma nota mostra o ID da fatura e o método de pagamento (cartão de crédito, boleto ou PIX).
Awaiting Iugu payment: o cliente voltou com um boleto ou PIX emitido. O pedido passa para Payment accepted quando a Iugu informa o pagamento.
Iugu payment on hold: o pagamento com cartão está autorizado, mas ainda não capturado (capture-o na Iugu, e o pedido será concluído assim que a Iugu informar que a fatura foi paga), o pagamento está em análise, a fatura foi paga apenas parcialmente, um chargeback foi aberto, a Iugu informou um valor ou uma moeda diferentes do carrinho (por exemplo, se o carrinho foi alterado depois que a fatura foi criada), ou o pagamento chegou depois que o pedido havia sido cancelado. As notas explicam o motivo. Verifique o pedido e atenda-o ou reembolse o pagamento.
Payment error: a fatura de um pedido em espera venceu sem pagamento. Se a Iugu informar depois que a fatura foi paga, o pedido passa para Payment accepted.
Canceled: a fatura de um pedido em espera foi cancelada na Iugu.
Refunded: o pagamento foi reembolsado integralmente pelo módulo ou no painel da Iugu.
Se outra fatura do mesmo carrinho também for paga, o pedido não é alterado. Uma nota pede que você reembolse o pagamento duplicado na Iugu.
Bloco de pagamento da Iugu
A página do pedido mostra um bloco Iugu payment com o ID da fatura da Iugu (com link para a fatura na Iugu), o método de pagamento, o status, o valor cobrado pela Iugu e o valor reembolsado, um selo Test mode para faturas de teste, o histórico de reembolsos e as Iugu notes do pedido.
Reembolsos
No bloco Iugu payment, informe o valor (o valor ainda não reembolsado vem preenchido), opcionalmente um motivo, e clique em Refund via Iugu. Confirme a pergunta Refund this amount through Iugu? This cannot be undone. É preciso ter permissão para editar pedidos. O reembolso é enviado com o token do modo em que a fatura foi criada, por isso esse token precisa estar preenchido.
Os reembolsos são calculados a partir do valor que a Iugu efetivamente cobrou pela fatura; portanto, após uma diferença de valor, você pode reembolsar até o que o cliente pagou, e não até o total do pedido. Só 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 bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o ID da fatura e o motivo. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Os reembolsos ficam disponíveis assim que a Iugu informa que a fatura foi paga.
O módulo não gera notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Iugu.
Um reembolso total feito no painel da Iugu coloca o pedido em Refunded com uma nota. Reembolsos parciais feitos no painel não são importados.
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 Iugu Gateway é o primeiro bloco de Modules > Module Manager > VibeFox Iugu Gateway > Configure, acima das configurações. Insira 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-iugu e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Somente funcionários com a permissão Configure para o 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 for alterado, 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 com várias lojas. Remover a chave da loja 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 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 pode 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, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática enquanto você trabalha no back office: uma vez por dia nos primeiros 14 dias após a chave ser inserida e, 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 Iugu não aparece no checkout: verifique se a licença está ativa, se Enable / Disable está ligado e se o token do modo ativo está preenchido: Test API token no modo de teste, Live API token no modo de produção. A moeda do carrinho deve ser BRL e o total deve ser de pelo menos R$ 1,00. Em Payment > Preferences, verifique se o módulo está permitido para a moeda BRL, o país do cliente e o grupo do cliente. A página de configurações mostra um aviso se o token ou a moeda estiverem incorretos.
O pagamento foi feito, mas nenhum pedido foi criado: a notificação da Iugu não chegou à sua loja ou não pôde ser verificada. Ative o Debug log e veja o campo Log na página do módulo. Confirme que sua loja está acessível pela internet no endereço da Notification URL e que o token do modo em que a fatura foi criada continua preenchido. A fatura também é verificada quando o cliente volta à loja após pagar.
Notification answers verification failed: a fatura não pôde ser lida na API da Iugu naquele momento, por exemplo por causa de um erro de rede, de um token incorreto ou da falta do token do modo da fatura. A Iugu tenta a notificação novamente.
Notification answers busy: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Iugu tenta a notificação novamente. O log mostra o motivo.
Notification answers invalid invoice id: a notificação não tinha um ID de fatura válido. Nada é alterado.
Pedido em Iugu payment on hold: leia as Iugu notes no bloco do pedido. Um pagamento com cartão aguarda captura, o pagamento está em análise, parcialmente pago ou contestado, o valor pago não coincide com o carrinho, ou o pagamento chegou depois que o pedido foi cancelado.
O cliente vê «Iugu payments are not available right now»: o token de API está ausente ou incorreto. Verifique o token do modo ativo.
O cliente vê «This order already has an Iugu payment that the store has to review»: uma fatura anterior do carrinho está autorizada, em análise ou parcialmente paga, mas nenhum pedido pôde ser criado. Verifique a fatura na Iugu e o log.
O reembolso falha: leia a mensagem no bloco. Pagamentos por boleto não podem ser reembolsados pela Iugu, pagamentos por PIX só podem ser reembolsados integralmente, e só faturas pagas podem ser reembolsadas. Se a mensagem disser que o pagamento foi feito no modo de teste ou de produção e nenhum token estiver configurado, insira o token desse modo. Se a Iugu não tiver confirmado o reembolso, verifique a fatura na Iugu antes de tentar novamente.
Desenvolvedores podem alterar a requisição da fatura, por exemplo limitando os métodos de pagamento com payable_with, no hook actionWcpIuguInvoiceData.
Desinstalação
Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Iugu Gateway 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 ativado, as configurações do gateway e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As referências e os reembolsos das faturas da Iugu e os status de pedido Awaiting Iugu payment e Iugu payment on hold são sempre mantidos, de modo que pedidos pagos antes ainda podem ser reembolsados e notificações atrasadas continuam sendo associadas após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Iugu é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Iugu.