VibeFox Vindi for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Moeda da loja: Real brasileiro (BRL). A Vindi cobra somente em BRL, por isso o método de pagamento fica oculto para carrinhos em qualquer outra moeda.
Conta na Vindi: você precisa da chave de API da sua conta na Vindi. A 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 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 VibeFox Vindi Gateway depois na lista de módulos e clique em Configure.
3. Informe a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
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 clique em Save. Teste um pagamento no modo sandbox e depois desative Sandbox mode para aceitar pagamentos reais.
Na instalação, o módulo cria dois status de pedido: Awaiting Vindi payment e Vindi 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; o módulo precisa estar permitido para BRL ali.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Vindi Gateway > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. 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, o método de pagamento não aparece na finalização de compra. Ao salvar, as chaves têm os espaços do início e do fim removidos. Se nenhum método de pagamento for selecionado, o cartão de crédito é selecionado e a página mostra Choose at least one payment method — credit card was selected. Um Title vazio não é salvo: a página mostra Enter a title for the payment method.
Vindi
Enable / Disable: Enable Vindi payments liga ou desliga o método de pagamento. Padrão: desligado.
Title: o nome do método de pagamento exibido na finalização de compra. Também é o nome do método de pagamento gravado no pedido. Padrão: Vindi. Obrigatório.
Description: o texto exibido abaixo do método 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. Produção e sandbox têm hosts e chaves separados. Cada pagamento guarda onde a sua fatura foi criada, então consultas, cancelamentos e reembolsos sempre usam esse ambiente.
Sandbox mode: cria novos pagamentos no sandbox da Vindi, usando sandbox-app.vindi.com.br com a chave de API do sandbox. Os clientes veem uma nota TEST MODE na finalização de compra: Vindi sandbox: no real charges. Padrão: ligado. Desligue para aceitar pagamentos reais.
Live API key: a chave privada da conta de produção na Vindi. Ela só é enviada à API da Vindi.
Sandbox API key: a chave privada da conta sandbox da Vindi.
As chaves salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-lo.
Clear saved keys: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Métodos de pagamento
Offered methods: os métodos que os clientes podem escolher. Padrão: cartão de crédito. Os métodos também precisam estar ativados na sua conta na Vindi.
Boleto, PIX e BolePix exigem o CPF ou CNPJ do cliente, que é solicitado na finalização de compra.
Notificações de pagamento (webhook)
O webhook informa à sua loja que uma fatura foi paga, cancelada, rejeitada ou reembolsada. O campo Webhook URL desta seção mostra a URL. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_vindi_gateway/webhook?token=... e contém um token secreto criado pelo módulo. Copie-a exatamente como as configurações a mostram. Na Vindi, acesse Settings > Webhooks, tanto na conta de produção quanto na conta sandbox, adicione esta URL e selecione estes eventos:
A Vindi não assina as suas notificações, por isso requisições com token ausente ou incorreto são rejeitadas, e cada notificação apenas faz o módulo consultar a fatura novamente pela API da Vindi antes que um pedido mude. Sem o webhook, um pagamento com cartão só é percebido quando o cliente faz o pedido de novo com o mesmo carrinho (a fatura paga é encontrada e o pedido é criado), e um pagamento de boleto ou PIX quando o cliente abre de novo a página de confirmação do pedido.
Avançado
Debug log: registra as chamadas à API e as notificações em logs/wc_vdi_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 está desligado. Chaves, token do webhook e dados dos clientes nunca são registrados. Padrão: desligado.
Log: mostra o tamanho e as últimas entradas do registro. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ligado, desinstalar o módulo remove as configurações, o token do webhook e os registros. Os pedidos e as referências das faturas da Vindi dos pedidos são mantidos. Padrão: desligado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Vindi). Quando mais de um método é oferecido, 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 o cartão de crédito não é oferecido; caso contrário, mostra Required for boleto and PIX. O campo é preenchido com o Identification number ou o número de VAT do endereço de cobrança, quando eles contêm um CPF ou CNPJ válido. O número é validado pelos dígitos verificadores. 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.
Quando o cliente confirma o pedido, o módulo cria um cliente na Vindi para este carrinho, a partir do endereço de cobrança, e uma fatura na Vindi pelo total do carrinho, em uma única parcela. Na Vindi, a fatura recebe o nome Order # seguido do número do carrinho.
Cartão de crédito: o cliente é enviado à página de fatura da Vindi e paga por lá. Nesse momento, ainda não existe pedido. A Vindi não tem URL de retorno para faturas, então o cliente não volta automaticamente à loja. O pedido é criado quando a Vindi confirma o pagamento pelo webhook. Se o cliente fizer o pedido novamente com o mesmo carrinho, a fatura pendente é oferecida de novo ou, se já estiver paga, o pedido é criado na hora.
Boleto, PIX e BolePix: a fatura é emitida na hora, o pedido é criado com o status Awaiting Vindi payment e o cliente vai para a página de confirmação do pedido. Ali, e nos detalhes do pedido na conta do cliente, uma seção Payment mostra o QR code PIX, o código PIX de copia e cola com um botão Copy code e a data de validade, além de um botão Open boleto. O e-mail de confirmação do pedido contém o código PIX e o link do boleto. Se a Vindi não devolver os dados do boleto ou do PIX, a fatura é cancelada e o cliente vê um erro.
O pedido só é marcado como pago depois que a Vindi confirma: o módulo lê a fatura pela API da Vindi e confere a moeda, se a fatura pertence ao carrinho (código do carrinho e cliente na Vindi) e se o valor pago é igual ao total do pedido. A página de confirmação do pedido consulta de novo, pela API, um pedido pendente, no máximo a cada 15 segundos. Quando o pagamento foi recebido, ela mostra Your payment with Vindi has been received. Enquanto a fatura está em análise na Vindi, mostra We are confirming your payment with Vindi. The order will be updated automatically — please do not pay again. Para um pedido cancelado, mostra This order was cancelled and its Vindi bill can no longer be paid. Please contact us if you have already paid.
Uma nova tentativa de pagamento para o mesmo carrinho reutiliza a fatura pendente na Vindi se o método, o valor e o ambiente forem os mesmos. Caso contrário, a fatura anterior é cancelada na Vindi antes de uma nova ser criada, para que o cliente não consiga pagar o mesmo carrinho duas vezes. Se a fatura anterior tiver sido paga nesse meio tempo, o pedido é criado e nenhuma nova fatura é emitida.
Se a Vindi não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com uma mensagem curta, por exemplo para conferir o CPF / CNPJ, o endereço de cobrança (rua, CEP, cidade e estado são obrigatórios para boleto), o e-mail ou o telefone, ou para informar que a Vindi está temporariamente indisponível. O motivo técnico é gravado no log.
O webhook funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.
O módulo aceita apenas 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 informado na página da Vindi.
Pedidos e reembolsos
Status do pedido
No order yet: um pagamento com cartão foi iniciado e a Vindi ainda não o confirmou. Existe apenas o carrinho.
Awaiting Vindi payment: um pagamento de boleto, PIX ou BolePix está aguardando (nota Awaiting ... payment at Vindi.). O pedido passa para Payment accepted quando a Vindi informa que a fatura foi paga.
Payment accepted: o pagamento foi confirmado. O pagamento é registrado com o ID da fatura na Vindi como ID da transação, e uma nota mostra a fatura na Vindi, o valor e o ambiente.
Vindi payment on hold: a fatura na Vindi está em análise, a fatura paga não confere com o pedido (moeda, valor, código do carrinho ou cliente na Vindi), ou a fatura foi paga depois que o pedido havia sido cancelado. A nota explica o motivo, e um valor pago é registrado no pedido. Confira o pedido e o estoque e, depois, conclua o pedido ou reembolse o pagamento.
Payment error: a Vindi recusou a tentativa de pagamento de um pedido aguardando. A nota mostra o motivo informado pela adquirente, se houver. O cliente ainda pode pagar a mesma fatura, e um pagamento posterior move o pedido para Payment accepted.
Canceled: a fatura de um pedido aguardando foi cancelada na Vindi. Quando você cancela um pedido na loja, a fatura pendente dele na Vindi também é cancelada, de modo que não pode mais ser paga. Se isso não for possível, uma nota pede que você cancele a fatura no painel da Vindi.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
Se uma segunda fatura for paga para um pedido que já está pago, o pedido não é alterado. Uma nota pede que você reembolse um dos pagamentos na Vindi.
Bloco de pagamento da Vindi
A página do pedido mostra um bloco Vindi payment com a fatura e a cobrança na Vindi, o ambiente (com a etiqueta Sandbox para pagamentos de sandbox), o método de pagamento, o status, o valor pago e reembolsado, o histórico de reembolsos, todas as Bills of this cart e as Vindi notes do pedido.
Reembolsos
No bloco Vindi payment, informe o valor (é preenchido o valor que ainda não foi reembolsado), opcionalmente um motivo, e clique em Refund via Vindi. Confirme a pergunta Refund this amount through Vindi? This cannot be undone. Reembolsos totais e parciais de pagamentos com cartão e PIX são suportados. Você precisa da permissão para editar pedidos; o acesso às páginas de módulos não é necessário. Os reembolsos são limitados ao valor que a Vindi efetivamente cobrou, então, depois de uma divergência, você pode reembolsar até o que o cliente pagou, e não o total do pedido. O reembolso é enviado no ambiente do pagamento (produção ou sandbox), por isso a chave de API desse ambiente precisa estar configurada. Um reembolso total também cancela a fatura na Vindi e coloca o pedido em Refunded; um reembolso parcial não altera o status. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com a cobrança da Vindi e o status. Se a Vindi ou a adquirente recusarem o reembolso, o bloco mostra o erro e nenhum reembolso é registrado. Os reembolsos estão disponíveis quando a Vindi informa que a fatura foi paga.
A Vindi não pode reembolsar pagamentos de boleto. O bloco mostra Vindi cannot refund boleto payments. Return the money to the customer by bank transfer and record the refund manually.
O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pela Vindi. Reembolsos feitos no painel da Vindi chegam pelo webhook charge_refunded e são adicionados às notas. O status do pedido não muda automaticamente; registre-os no PrestaShop com um reembolso manual, se necessário.
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 Vindi Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Vindi 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 estão a linha Product: presta-payment-vindi e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Apenas 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 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, inclusive em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere-a na sua conta em 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. 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 na finalização de compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: as faturas já criadas continuam sendo confirmadas pelo webhook da Vindi, 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. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
A Vindi não aparece na finalização de compra: verifique se a licença está ativa, se Enable / Disable está ligado, se a moeda do carrinho é BRL, se pelo menos um método está selecionado em Offered methods e se o modo atual tem uma chave de API: Sandbox API key no modo sandbox, Live API key no modo produção. A página de configurações mostra um aviso quando a chave está faltando ou a moeda não é BRL. Em Payment > Preferences, confira se o módulo está permitido para BRL, para o país do cliente e para o grupo do cliente.
O pagamento foi feito, mas nenhum pedido foi criado ou o pedido continua em Awaiting Vindi payment: 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 é exatamente a que aparece nas configurações, incluindo o token, e se os quatro eventos estão selecionados.
O webhook responde Forbidden: o token na URL está faltando ou incorreto. Copie a URL novamente nas configurações.
O webhook responde Verification failed, retry later: a fatura não pôde ser lida pela API da Vindi (por exemplo, a chave de API desse ambiente foi removida), o carrinho estava sendo atualizado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Vindi envia a notificação novamente. O log mostra o motivo.
A URL do webhook mostra Method not allowed no navegador: isso é normal. A URL aceita apenas requisições da Vindi.
O cliente vê This payment method is temporarily unavailable: a Vindi recusou a chave de API. Verifique a chave do modo atual.
O cliente vê um erro ao fazer o pedido: veja o campo Log na página do módulo. 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á em Vindi payment on hold: leia as notas no bloco Vindi payment (veja Status do pedido) e, depois, conclua o pedido ou reembolse o pagamento.
Pedidos antigos de sandbox depois de mudar para produção: cada pagamento mantém o ambiente da sua fatura. Consultas, cancelamentos e reembolsos de pedidos de 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.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Vindi 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 ligado, as configurações, o token do webhook e os registros são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. As faturas e os reembolsos da Vindi dos pedidos e os status de pedido Awaiting Vindi payment e Vindi payment on hold são sempre mantidos, para que pedidos pagos antes possam ser reembolsados depois de uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
A Vindi é uma marca registrada de seu respectivo titular. Este módulo não é afiliado à Vindi nem endossado por ela.