VibeFox Vindi for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não ativa sem ele.
PHP: 8.0 ou superior.
Moeda da loja: Real brasileiro (BRL). A Vindi cobra apenas em BRL, por isso a forma de pagamento fica oculta para qualquer outra moeda.
Conta na Vindi: você precisa da chave de API da sua conta na Vindi. O sandbox da Vindi é uma conta de teste separada, com chave própria. Boleto, PIX e BolePix também precisam estar ativados na sua conta na Vindi se você quiser oferecê-los.
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, clique em Install Now e depois em Activate. Você também pode enviar a pasta wcp_vindi_gateway para /wp-content/plugins/ por FTP.
2. Abra as configurações: WooCommerce > Settings > Payments > Vindi > Manage, ou clique em Settings abaixo do nome do plugin na página de Plugins.
3. Informe sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
4. Cole a Sandbox API key e, quando estiver pronto, a Live API key. Escolha os Offered methods.
5. Copie a URL do webhook das configurações para a Vindi (veja Configuração).
6. Ative Enable / Disable e salve. 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 > Vindi. Acima dos campos, a página avisa quando a moeda da loja não é BRL ou quando a chave de API do modo atual está vazia. Nos dois casos, a forma de pagamento não aparece na finalização de compra. Na lista de formas de pagamento, a Vindi é marcada como pendente de configuração até que o modo atual tenha uma chave de API. Ao salvar, as chaves são limpas e, se nenhuma forma de pagamento estiver selecionada, o cartão de crédito é selecionado e a página mostra Choose at least one payment method — credit card was selected.
Geral
Enable / Disable: Enable Vindi payments liga ou desliga a forma de pagamento. Padrão: off.
Title: o nome da forma de pagamento exibido na finalização de compra. Padrão: Vindi.
Description: o texto exibido abaixo da forma de pagamento na finalização de compra. Padrão: Pay by credit card on the secure Vindi page, or by boleto / PIX.
Chaves de API
Crie as chaves no painel da Vindi, em Settings > API keys: em app.vindi.com.br para produção e em sandbox-app.vindi.com.br para o sandbox. Cada pedido guarda onde a sua fatura foi criada, então consultas, cancelamentos e reembolsos sempre usam esse ambiente.
Sandbox mode: Create new payments in the Vindi sandbox usa sandbox-app.vindi.com.br com a chave de API do sandbox. Os clientes veem um aviso TEST MODE na finalização de compra: Vindi sandbox: no real charges. Padrão: on. Desmarque para aceitar pagamentos reais.
Live API key: a chave privada da conta de produção na Vindi. Ela é enviada somente à API da Vindi.
Sandbox API key: a chave privada da conta sandbox da Vindi.
Formas de pagamento
Offered methods: as formas que o cliente pode escolher. Padrão: credit card. As formas também precisam estar ativadas na sua conta na Vindi.
Notificações de pagamento (webhook)
O webhook avisa a sua loja que uma fatura foi paga, cancelada ou reembolsada. Esta seção das configurações mostra a URL do webhook. Ela tem a forma https://your-site/wc-api/webhook_wc_vindi/?token=... e contém um token secreto criado pelo plugin. Copie-a exatamente como as configurações mostram. Na Vindi, acesse Settings > Webhooks, tanto na conta de produção quanto na conta sandbox, adicione esta URL e selecione estes eventos:
Solicitações com token ausente ou incorreto são recusadas. Cada notificação apenas faz o plugin reler a fatura pela API da Vindi antes que um pedido seja alterado. Sem o webhook, pagamentos com cartão, boleto e PIX só são confirmados quando o cliente abre a página de pedido recebido.
Avançado
Debug log: Log API calls and notifications grava os detalhes em WooCommerce > Status > Logs, origem wcp_vindi_gateway. Erros e avisos são sempre registrados, mesmo com essa opção desligada. Chaves e dados dos clientes nunca são registrados. Padrão: off.
Delete data on uninstall: Remove the settings, webhook token and logs when the plugin is deleted. Padrão: off.
Finalização de compra
O cliente escolhe a forma de pagamento (por padrão, Vindi). Quando mais de uma forma é oferecida, a caixa de pagamento mostra Pay with e uma escolha entre cartão de crédito, boleto, PIX ou BolePix. Quando boleto, PIX ou BolePix é oferecido, a caixa também tem um campo CPF or CNPJ. Ele é obrigatório quando somente essas formas são oferecidas; caso contrário, aparece Required for boleto and PIX. O número é validado pelos dígitos verificadores. Na finalização de compra clássica, o campo não aparece quando o Brazilian Market on WooCommerce está ativo, porque esse plugin já solicita o CPF / CNPJ. Nesse caso, são usados o CPF / CNPJ, o número e o bairro dele. Se algo estiver faltando, o cliente vê Please choose how you want to pay with Vindi., Please enter a valid CPF or CNPJ. ou Please enter your CPF or CNPJ — it is required for boleto and PIX.
Ao finalizar o pedido, o plugin cria na Vindi um cliente para este pedido, a partir dos dados de cobrança, e uma fatura na Vindi pelo total do pedido, em uma única parcela.
Credit card: o cliente é enviado à página de fatura da Vindi e paga por lá. A Vindi não tem URL de retorno para faturas, então o cliente não volta automaticamente para a loja. O pedido é confirmado pelo webhook ou quando o cliente abre a página de pedido recebido. Enquanto o pagamento não for concluído, essa página e o pedido em My account mostram Your payment has not been completed yet. e um botão Pay at Vindi.
Boleto, PIX e BolePix: a fatura é emitida na hora, o pedido fica Em espera e o cliente vai para a página de pedido recebido. Lá, e em My account > Orders, uma seção Payment mostra o QR code do PIX, o código PIX de copia e cola com o botão Copy code e a data de vencimento, além do botão Open boleto. O e-mail de pedido em espera e o e-mail da fatura contêm o código PIX e o link do boleto.
O pedido só é marcado como pago depois que a Vindi confirma: o plugin lê a fatura pela API da Vindi e confere se ela pertence ao pedido (código do pedido e cliente na Vindi) e se o valor pago é igual ao total do pedido.
O cliente pode pagar novamente um pedido não pago pela página Pay for order. Se a forma, o valor e o ambiente forem os mesmos, a fatura pendente na Vindi é reaproveitada. Caso contrário, ela é cancelada na Vindi antes de uma nova ser criada, para que o cliente não possa pagar o mesmo pedido duas vezes. Se a fatura anterior tiver sido paga nesse meio tempo, o pedido é marcado como pago e nenhuma nova fatura é criada.
Se a Vindi não conseguir iniciar o pagamento, o cliente vê uma mensagem curta, por exemplo para conferir o CPF / CNPJ, o endereço de cobrança, o e-mail ou o telefone, ou informando que a Vindi está temporariamente indisponível. Se o mesmo pedido estiver sendo processado por outra requisição naquele momento, o cliente é orientado a aguardar um instante e tentar de novo.
A forma de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. Ela é compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O plugin aceita pagamentos únicos, em uma parcela. Não há assinaturas ou cobranças recorrentes, cartões salvos, parcelamento nem formulário de cartão no seu site: o cartão é sempre digitado na página da Vindi.
Pedidos e reembolsos
Status do pedido
Pending payment: um pagamento com cartão foi iniciado e a Vindi ainda não o confirmou.
On hold: um pagamento de boleto, PIX ou BolePix está aguardando (nota Awaiting ... payment at Vindi.), ou a fatura na Vindi está em análise.
Processing or Completed: o pagamento foi confirmado. O status é definido da forma padrão do WooCommerce: Processando, ou Concluído para pedidos com apenas produtos virtuais para download. A nota do pedido mostra a fatura na Vindi, o valor e o ambiente. O ID da transação é o ID da fatura na Vindi.
On hold after payment: a fatura paga não corresponde ao pedido (valor, código do pedido ou cliente na Vindi), ou a fatura foi paga depois que o pedido havia sido cancelado. A nota do pedido explica o motivo. Confira o pedido e o estoque e, em seguida, conclua o pedido ou reembolse o pagamento.
Failed: a Vindi recusou a tentativa de pagamento. A nota mostra o motivo informado pela adquirente, se houver. O cliente ainda pode pagar a mesma fatura, e um pagamento posterior conclui o pedido.
Cancelled: a fatura foi cancelada na Vindi, ou o pedido foi cancelado por você, pelo cliente ou pelo tempo limite de reserva de estoque do WooCommerce. Quando um pedido é cancelado na loja, a fatura pendente dele na Vindi também é cancelada, para que não possa mais ser paga. Se isso não for possível, uma nota pede que você cancele a fatura no painel da Vindi. Antes que o tempo limite de reserva de estoque cancele um pedido, a fatura é verificada: se ela tiver sido paga nesse meio tempo, o pedido é marcado como pago.
Se uma segunda fatura for paga para um pedido que já está pago, o pedido não é alterado novamente. Uma nota pede que você reembolse um pagamento na Vindi.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Vindi. São aceitos reembolsos totais e parciais de pagamentos com cartão e PIX. Um reembolso total também cancela a fatura na Vindi. O reembolso é enviado no ambiente do pagamento (produção ou sandbox), por isso a chave de API desse ambiente precisa estar configurada. Um reembolso bem-sucedido é adicionado às notas do pedido, com a cobrança da Vindi e o status. Se a Vindi ou a adquirente recusarem o reembolso, o WooCommerce exibe o erro e nenhum reembolso é registrado.
A Vindi não pode reembolsar pagamentos de boleto. O plugin mostra Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.
Reembolsos feitos no painel da Vindi chegam pelo webhook charge_refunded e são adicionados às notas do pedido. Eles não são registrados automaticamente como reembolsos do WooCommerce. Se necessário, crie um reembolso manual no WooCommerce sem usar Refund via Vindi.
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 > Vindi. 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 informar 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 na sua conta na vibefox.net.
Sem uma chave ativa, a Vindi 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 que estiverem logados continuam vendo a forma de pagamento, marcada 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 de Plugins e nas páginas do WooCommerce. Os 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 a renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
A Vindi não aparece na finalização de compra: confira se a licença está ativa, se Enable / Disable está ligado, se a moeda da loja é BRL, se pelo menos uma forma está selecionada em Offered methods e se o modo atual tem chave de API: Sandbox API key no modo sandbox, Live API key no modo de produção. A página de configurações mostra um aviso quando a chave está faltando ou a moeda não é BRL.
O pagamento foi feito, mas o pedido continua em Pending payment ou On hold: o webhook não está funcionando. Na Vindi, confira se o webhook existe na conta que você usa (produção ou sandbox), se a URL dele é exatamente a mostrada nas configurações, incluindo o token, e se os quatro eventos estão selecionados. O pedido também é confirmado quando o cliente abre a página de pedido recebido.
O webhook responde Forbidden: o token na URL está ausente ou incorreto. Copie a URL novamente das configurações.
O webhook responde Verification failed, retry later ou Order busy, retry later: a fatura não pôde ser lida pela API da Vindi (por exemplo, a chave de API desse ambiente foi removida), ou o pedido estava sendo atualizado por outra requisição no mesmo momento. A Vindi envia a notificação novamente.
O cliente vê This payment method is temporarily unavailable: a Vindi recusou a chave de API. Confira a chave do modo atual.
O cliente vê um erro ao finalizar o pedido: abra as notas do pedido ou o log em WooCommerce > Status > Logs, origem wcp_vindi_gateway. Os erros são registrados mesmo com Debug log desligado. Para boleto, o endereço de cobrança precisa ter rua, CEP, cidade e estado.
O pedido está On hold após o pagamento: leia a nota do pedido. O valor pago, o código do pedido ou o cliente na Vindi não correspondiam ao pedido, ou o pagamento chegou depois que o pedido foi cancelado. Conclua o pedido ou reembolse o pagamento.
Pedidos antigos do sandbox depois da troca para produção: cada pedido mantém o ambiente da sua fatura. Consultas, cancelamentos e reembolsos de pedidos do sandbox continuam usando a chave do sandbox enquanto ela estiver nas configurações.
O reembolso falha: leia a mensagem. Pagamentos de boleto não podem ser reembolsados pela Vindi, e a chave de API do ambiente do pagamento precisa estar configurada.
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 no 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 da licença deste plugin são sempre removidos. As configurações do gateway, o token do webhook, os outros dados armazenados pelo plugin e os logs são removidos somente se Delete data on uninstall estava ligado. Caso contrário, eles permanecem para uma reinstalação futura. Os pedidos existentes mantêm as notas de pagamento, os IDs de transação e os dados da Vindi.
Vindi é uma marca de seu respectivo titular. Este plugin não é afiliado nem endossado pela Vindi.