VibeFox Viva Wallet for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Conta Viva: uma conta de comerciante Viva. Você pode usar uma conta de demonstração (demo.vivapayments.com) para testes e uma conta de produção (www.vivapayments.com) para pagamentos reais. Cada conta tem suas próprias credenciais. Para os pagamentos, você precisa das credenciais do Smart Checkout (Client ID e Client Secret) e do Source Code de uma fonte de pagamento. O Merchant ID e a API Key são opcionais: são usados apenas para responder à verificação da URL do webhook pela Viva.
Moeda da loja: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK ou CHF. Em outras moedas, o método de pagamento fica oculto na finalização de compra.
Site público com HTTPS: para os webhooks, seu site deve estar acessível pela internet por HTTPS.
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_viva_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Viva Wallet > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira as credenciais da conta de demonstração e/ou de produção da Viva e configure a fonte de pagamento e o webhook (veja Configuração).
6. Ative Enable/Disable. Faça um pagamento de demonstração com um cartão de demonstração da Viva enquanto o Test Mode estiver ativado e depois desmarque o Test Mode para passar ao modo de produção.
Configuração
Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Viva Wallet. Acima dos campos, a página avisa quando o modo atual não tem Client ID, Client Secret ou Source Code (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered., ou Live no modo de produção) e quando a moeda da loja não é compatível. Com o modo de teste ativado, ela mostra Test mode is on: payments go to the Viva demo environment. Na lista de métodos de pagamento, o Viva Wallet aparece como precisando de configuração até que o modo atual tenha esses três valores.
Geral
Enable/Disable: Enable Viva Wallet payment gateway ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que os clientes veem na finalização de compra. Padrão: Viva Wallet.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.
Test Mode: Use the Viva demo environment (demo.vivapayments.com). Os novos pagamentos e as chamadas de API usam as credenciais da conta de demonstração. Nenhum valor real é cobrado, e na finalização de compra a descrição termina com (Test mode: use Viva demo cards, no real money is charged.) Padrão: ativado. Desmarque para receber pagamentos reais com a conta de produção. Pagamentos já feitos continuam sendo verificados e reembolsados no ambiente em que foram realizados.
Conta de demonstração (modo de teste) e conta de produção
As duas seções têm os mesmos campos: um conjunto para a conta de demonstração e outro para a conta de produção. Na sua conta Viva, abra Settings > API Access e copie as credenciais do Smart Checkout (Client ID, Client Secret), o Merchant ID e a API Key. O Source Code fica em Sales > Online payments > Websites / apps.
Client ID (Demo) / Client ID (Live): o Client ID OAuth 2.0 do Smart Checkout da conta. Obrigatório.
Client Secret (Demo) / Client Secret (Live): o Client Secret OAuth 2.0 do Smart Checkout da conta. Obrigatório.
Source Code (Demo) / Source Code (Live): o código de 4 dígitos da fonte de pagamento da conta. Seus Success URL e Failure URL devem apontar para esta loja (veja abaixo). Obrigatório.
Merchant ID (Demo) / Merchant ID (Live): opcional. Usado apenas para responder à verificação da URL do webhook pela Viva.
API Key (Demo) / API Key (Live): opcional. Usada apenas para responder à verificação da URL do webhook pela Viva.
URLs de retorno e webhook
Payment source: em Sales > Online payments > Websites / apps, crie uma fonte de pagamento para o domínio da sua loja, em cada conta que você usar. Como Success URL e Failure URL, informe os caminhos após o domínio dos dois endereços mostrados nas configurações, que têm este formato: https://your-site/wc-api/viva_payment_success/ e https://your-site/wc-api/viva_payment_fail/.
Webhook: em Settings > API Access > Webhooks, adicione a URL mostrada nas configurações, que tem este formato https://your-site/wp-json/wc-viva-gateway/v1/webhook, para estes eventos:
A Viva verifica a URL antes de salvá-la. O plugin responde com a chave de verificação da sua conta: ele busca a chave com o Merchant ID e a API Key do modo atual, ou usa a chave informada abaixo. Os webhooks confirmam pagamentos mesmo quando o cliente fecha o navegador. Os webhooks da Viva não são assinados, então o plugin nunca confia no webhook sozinho: cada pagamento é verificado pela API da Viva antes de o pedido ser marcado como pago. Sem o webhook, um pedido só é confirmado quando o cliente volta à loja depois de pagar.
Webhook Verification Key: opcional. Deixe em branco para buscar a chave automaticamente com o Merchant ID e a API Key do modo atual, ou cole aqui a chave de verificação da sua conta Viva.
Configurações avançadas
Order Status After Payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido de imediato, sem uma segunda mudança de status.
Brand Color: um código de cor HEX de 6 dígitos para a página de pagamento da Viva, por exemplo 0000ff. Um # inicial é removido. Deixe em branco para a cor padrão. Qualquer outro valor é recusado ao salvar e o valor anterior é mantido.
Debug Logging: Enable logging grava as requisições de API em WooCommerce > Status > Logs, origem wcp_viva_gateway. Chaves e dados dos clientes não são registrados. Erros são sempre registrados, mesmo quando a opção está desativada. Padrão: desativado.
Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. Quando ativado, ao excluir o plugin são removidos as configurações, a tabela de tentativas de pagamento e os logs do plugin. Notas e dados dos pedidos permanecem. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Viva Wallet) e faz o pedido. O plugin cria um pedido de pagamento na Viva pelo valor total do pedido, na moeda do pedido, e envia o cliente para a página Viva Smart Checkout. Lá o cliente paga com um dos métodos ativados na sua conta Viva, como cartões, Apple Pay ou Google Pay. O e-mail, o nome, o telefone e o país do cliente são repassados à Viva, e a página abre no idioma do seu site, se a Viva oferecer suporte; caso contrário, em inglês. O pagamento aparece na Viva como WooCommerce # e o número do pedido. O pedido de pagamento da Viva expira após 30 minutos.
Depois de pagar, o cliente volta à página de pedido recebido da sua loja. O pedido só é marcado como pago depois que a Viva confirma: o plugin relê a transação pela API da Viva, no retorno do cliente e no webhook. Se o pagamento ainda não estiver confirmado, a página mostra We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.
Se o pagamento falhar ou o cliente cancelar na página da Viva, o status do pedido não muda. O cliente é enviado à página Pay for order com The Viva Wallet payment was not completed. Please try again or choose another payment method. ou The Viva Wallet payment was cancelled. You can try again or choose another payment method., e pode pagar novamente.
Se a Viva não conseguir iniciar o pagamento, o cliente vê Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (credenciais ausentes ou incorretas) ou We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. O motivo técnico é gravado no log.
O método de pagamento funciona na finalização de compra clássica, no bloco de Finalizar compra e na página Pay for order, onde a moeda desse pedido é verificada. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita apenas pagamentos únicos, cobrados de imediato na página da Viva. Não há pré-autorização e captura, parcelamento, cartões salvos, WooCommerce Subscriptions, Viva Native Checkout (campos de cartão na sua própria página) nem terminais POS. Quando o cliente inicia uma nova tentativa, o pedido de pagamento antigo e não pago na Viva não é cancelado; a Viva o expira após 30 minutos.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à Viva e ainda não pagou, o pagamento ainda não foi confirmado, ou o pagamento falhou ou foi cancelado. Uma nota mostra o pedido de pagamento da Viva e o ambiente (demonstração ou produção). Tentativas com falha e canceladas são adicionadas às notas do pedido, e o cliente pode pagar novamente.
Processing, Completed or On Hold: o pagamento foi confirmado. O status segue Order Status After Payment. A nota do pedido mostra o valor, o ID da transação na Viva, o ambiente e como foi confirmado (webhook ou retorno do cliente).
On hold for review: a Viva informou um valor ou moeda diferente do total do pedido, por exemplo quando o pedido foi editado depois que o cliente começou a pagar. A nota Viva Wallet payment held for review informa o motivo. Compare o pagamento no painel da Viva com o pedido e conclua-o ou reembolse-o manualmente.
Um pagamento que chega para um pedido cancelado ou reembolsado não altera o status do pedido; uma nota pede que você restaure o pedido ou reembolse o pagamento no painel da Viva. Se um segundo pagamento chegar para um pedido já pago, o pedido não é alterado novamente; uma nota pede que você reembolse a duplicata no painel da Viva.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Viva Wallet. Reembolsos totais e parciais são aceitos para pedidos com uma transação Viva confirmada. O reembolso é enviado à conta em que o pagamento foi feito (demonstração ou produção), na moeda do pagamento, por isso o Client ID e o Client Secret dessa conta precisam estar informados. Se a Viva não aceitar o reembolso, o WooCommerce mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado às notas do pedido com a transação de reembolso da Viva.
Reembolsos feitos no painel da Viva não são importados. Se necessário, crie um reembolso manual no WooCommerce sem Refund via Viva Wallet.
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 > Viva Wallet. 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 em vibefox.net.
Uma chave funciona em um domínio. Remover a chave de um site não libera a vaga do domínio. Libere a vaga na sua conta em vibefox.net.
Sem uma chave ativa, o Viva Wallet não é exibido 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 conectados ainda veem o método de pagamento, marcado com (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. Os pedidos existentes não são afetados: os 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
O Viva Wallet não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se o modo atual tem o seu Client ID, Client Secret e Source Code (os campos Demo no modo de teste, os campos Live no modo de produção). A moeda da loja (na página Pay for order, a moeda do pedido) deve ser uma de EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK ou CHF. A página de configurações mostra um aviso quando algo está faltando.
O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não está funcionando. Na Viva, verifique se o webhook existe na conta que você usa (demonstração ou produção), se a URL é exatamente a mostrada nas configurações e se Transaction Payment Created está selecionado. Confira se o Client ID e o Client Secret da conta desse pagamento ainda estão informados: o plugin precisa deles para verificar o pagamento. Os detalhes estão em WooCommerce > Status > Logs, origem wcp_viva_gateway.
A Viva não consegue verificar a URL do webhook: informe o Merchant ID e a API Key do modo atual (ou a própria chave de verificação em Webhook Verification Key), salve e verifique novamente na Viva. Para verificar o webhook da outra conta, mude antes o Test Mode ou informe a chave dessa conta.
O webhook responde com erro: a Viva mostra a resposta da sua loja e reenvia os webhooks que falharam. verification_failed (HTTP 500) significa que não foi possível acessar a API da Viva para verificar o pagamento. busy (HTTP 503) significa que o pedido estava sendo processado por outra requisição no mesmo momento. transaction_not_found (HTTP 404) significa que a transação não existe na conta desse pagamento, por exemplo por credenciais incorretas. Eventos de pagamentos de outras lojas na mesma conta da Viva recebem a resposta ignored.
O cliente vê um erro ao fazer o pedido: ative o Debug Logging e veja WooCommerce > Status > Logs, origem wcp_viva_gateway. Client ID ou Client Secret incorretos, ou Source Code ausente, geram a mensagem de que os pagamentos com Viva Wallet não estão disponíveis. Se a Viva não puder ser acessada ou recusar o pedido de pagamento, por exemplo porque o Source Code pertence a outra conta, o cliente recebe a mensagem de que a loja não conseguiu se conectar ao Viva Wallet.
O pedido fica On hold após o pagamento: leia a nota do pedido. O valor ou a moeda pagos foram diferentes do pedido. Conclua o pedido ou reembolse o pagamento.
O reembolso falha com This payment was made in the Viva demo (or live) environment: o Client ID e o Client Secret da conta em que o pagamento foi feito não estão informados. Informe-os e tente novamente. Outros erros de reembolso mostram o código HTTP e a mensagem da Viva.
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 não puder ser acessado, o plugin continua funcionando com o último status conhecido.
Para desenvolvedores: o filtro viva_wp_supported_currencies ativa moedas adicionais suportadas pela sua conta Viva, viva_wp_create_order_payload altera a requisição do pedido de pagamento (valor, moeda e Source Code devem ser mantidos) e viva_wp_icon altera o ícone da finalização de compra.
Desinstalação
Desativar o plugin mantém todos os dados; apenas os tokens de acesso da Viva em cache são removidos. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin, assim como os tokens em cache e as chaves de webhook, são sempre removidos. As configurações, a tabela de tentativas de pagamento e os logs do plugin (arquivos de log, incluindo os rotacionados, e entradas do banco de dados) são removidos somente se Delete Data on Uninstall estava ativado. Caso contrário, permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
Viva Wallet é uma marca de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Viva Wallet.