VibeFox Viva Wallet for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
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 as 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. Merchant ID e API Key são opcionais: eles são usados apenas para responder à verificação da URL do webhook pela Viva.
Moeda: 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 da compra.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único domínio.
Instalação
1. No back office, acesse 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, mais tarde, encontre VibeFox Viva Wallet Gateway na lista de módulos e clique em Configure.
3. Insira 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. Insira as credenciais da conta de demonstração e/ou de produção da Viva e configure a fonte de pagamento e o webhook na sua conta Viva (veja Configuração).
5. Ative Enable/Disable e clique em Save. Faça um pagamento de demonstração com um cartão de demonstração da Viva enquanto o Test Mode estiver ativado e, depois, desative o Test Mode para entrar em produção.
Ao instalar, o módulo cria o status de pedido Viva Wallet payment on hold. O módulo é oferecido para os países ativos no momento da instalação. Você pode alterar moedas, países e grupos de clientes em Payment > Preferences; novos países podem ser adicionados ali depois.
Configuração
Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Viva Wallet 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 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 padrão da loja não é suportada. Enquanto o modo de teste estiver ativado, ela mostra Test mode is on: payments go to the Viva demo environment. Salvar as configurações remove os tokens de acesso da Viva em cache, para que as novas credenciais sejam usadas imediatamente.
Viva Wallet
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 o cliente vê na finalização da compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Viva Wallet. Obrigatório: um título vazio não é salvo e a página mostra Enter a title for the payment method.
Description: o texto exibido abaixo do método de pagamento na finalização da compra. Padrão: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.
Test Mode: usa o ambiente de demonstração da Viva (demo.vivapayments.com). Novos pagamentos e chamadas de API usam as credenciais da conta de demonstração. Nenhum dinheiro real é cobrado, e na finalização da compra o cliente vê (Test mode: use Viva demo cards, no real money is charged.) Padrão: ativado. Desative para receber pagamentos reais com a conta de produção. Pagamentos já feitos continuam sendo verificados e reembolsados no ambiente em que foram feitos.
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 OAuth 2.0 Client ID do Smart Checkout da conta. Obrigatório para pagamentos.
Client Secret (Demo) / Client Secret (Live): o OAuth 2.0 Client Secret do Smart Checkout da conta. Obrigatório para pagamentos.
Source Code (Demo) / Source Code (Live): o código de 4 dígitos da fonte de pagamento da conta. Os seus Success URL e Failure URL devem apontar para esta loja (veja abaixo). Obrigatório para pagamentos.
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.
Client Secrets e API Keys salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.
Clear saved secrets: marque um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.
URLs de retorno e webhook
Addresses for the Viva account: este campo mostra os três endereços da sua loja para informar na conta Viva. Com URLs amigáveis, eles têm esta aparência: https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail e https://your-shop/module/wcp_viva_gateway/webhook, possivelmente com um código de idioma como /en/. Copie-os exatamente como as configurações os mostram.
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 a parte dos endereços de sucesso e de falha que vem depois do domínio.
Webhook: em Settings > API Access > Webhooks, adicione o endereço do webhook para estes eventos:
A Viva verifica a URL antes de salvá-la. O módulo responde com a chave de verificação da sua conta: ele a obtém 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 módulo nunca confia apenas no webhook: cada pagamento é verificado pela API da Viva antes de o pedido ser criado. Sem o webhook, um pedido só é criado quando o cliente volta à loja após pagar.
Webhook Verification Key: opcional. Deixe vazio para obter 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 vazio para a cor padrão. Qualquer outro valor não é salvo: a página mostra Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.
Debug Logging: grava as requisições de API em logs/viva_wp_debug.log.php na pasta do módulo. O arquivo não pode ser aberto pela web. Chaves, tokens e dados de clientes não são registrados. Erros são sempre registrados, mesmo quando esta opção está desativada. Padrão: desativado.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete Data on Uninstall: quando ativado, ao desinstalar o módulo as configurações e os logs do módulo são removidos. Pedidos e os respectivos dados de pagamento (tentativas de pagamento da Viva, reembolsos, status do pedido) nunca são excluídos. Padrão: desativado.
Finalização da compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Viva Wallet) e vê a nota You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). Após confirmar, o módulo cria um pedido de pagamento na Viva pelo valor total do carrinho, na moeda do carrinho, 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. O e-mail, o nome, o telefone e o país do cliente são enviados à Viva, e a página abre no idioma do carrinho, se a Viva o suportar. Na Viva, o pagamento aparece como Cart #, o número do carrinho e o nome da sua loja. O pedido de pagamento na Viva expira após 30 minutos. Neste ponto, ainda não existe nenhum pedido.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a Viva confirma: o módulo relê a transação pela API da Viva, no retorno do cliente e no webhook. Então o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Se o pagamento ainda não estiver confirmado, uma página Payment confirmation mostra We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. com os botões Check again e Back to checkout; o webhook cria o pedido assim que a Viva confirma o pagamento.
Se o pagamento falhar ou o cliente cancelar na página da Viva, nenhum pedido é criado e o carrinho é mantido. O cliente volta à finalização da compra 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 permanece na finalização da compra com 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.
As páginas de retorno mostram a confirmação do pedido somente para o cliente que pagou. Qualquer outra pessoa que abra o endereço de retorno é redirecionada para o histórico de pedidos ou para a finalização da compra, sem detalhes do pedido.
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, cobrados imediatamente na página da Viva. Não há pré-autorização e captura, parcelamento, cartões salvos, assinaturas, 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
Ainda sem pedido: o cliente foi enviado à Viva e não pagou, o pagamento falhou ou foi cancelado, ou a Viva ainda não finalizou o pagamento. Existe apenas o carrinho, e o cliente pode pagar novamente.
Payment accepted, Delivered ou Viva Wallet payment on hold: o pagamento foi confirmado. O status segue Order Status After Payment. O pagamento é registrado com o ID da transação na Viva, e uma nota mostra o valor, a transação, o código do pedido na Viva, o ambiente (demonstração ou produção) e como foi confirmado (webhook ou retorno do cliente).
Viva Wallet payment on hold após uma divergência: a Viva informou um valor ou uma moeda diferentes do total do carrinho, por exemplo quando o carrinho foi alterado depois que o cliente começou a pagar. O pedido é criado sem um pagamento registrado, e a nota Viva Wallet payment held for review indica o motivo. O cliente vê a página padrão de confirmação do pedido, sem a promessa de uma confirmação da Viva. Compare o pagamento no painel da Viva com o pedido e atenda ou reembolse manualmente. Se um pagamento correspondente ao mesmo carrinho chegar depois, o pedido passa para o status de pago.
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; uma nota pede que você reembolse a duplicata no painel da Viva.
Bloco Viva Wallet payment
A página do pedido mostra um bloco Viva Wallet payment com o código do pedido na Viva, o ID da transação, o ambiente e o Source Code, o status da Viva, os valores pagos e reembolsados, um selo Demo para pagamentos de demonstração, o histórico de reembolsos, as tentativas de pagamento do carrinho (quando houve mais de uma) e as Viva Wallet notes do pedido.
Reembolsos
No bloco Viva Wallet payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Viva Wallet. Confirme a pergunta Refund this amount via Viva Wallet? This cannot be undone. Reembolsos totais e parciais são suportados para pedidos com uma transação confirmada na Viva. Você precisa ter permissão para editar pedidos; acesso aos módulos não é necessário. Você pode reembolsar até o valor que a Viva cobrou pelo pagamento, mesmo que o pedido tenha sido editado depois. O reembolso é enviado para a 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 bloco mostra o erro e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com a transação de reembolso da Viva. Um reembolso total coloca o pedido em Refunded. Um reembolso parcial não altera o status. Um pedido retido para revisão sem pagamento confirmado não pode ser reembolsado pelo bloco.
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 Viva. Reembolsos feitos no painel da Viva não são importados. Atualize o pedido manualmente, 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 Viva Wallet Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure, acima das configurações. Informe 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 informar outra chave e Remove key para remover a chave desta loja. Abaixo deles estão a linha Product: presta-payment-viva e o link Manage licenses and domains in your account, que abre a sua conta 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 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 único domínio: o domínio da loja principal, também em uma configuração multiloja. Remover a chave da loja não libera a vaga de domínio. Libere a vaga na sua conta vibefox.net.
Sem uma chave ativa, o Viva Wallet não é exibido aos clientes na finalização da 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á logado no 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 testá-lo na finalização da compra. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: os pagamentos já iniciados continuam sendo confirmados pelo webhook da Viva e pelo retorno à loja, 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 informada 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
O Viva Wallet não aparece na finalização da compra: verifique se a licença está ativa, se o Enable/Disable está ativado e se o modo atual tem o seu Client ID, o Client Secret e o Source Code (os campos Demo no modo de teste, os campos Live no modo de produção). A moeda do carrinho deve ser uma de EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK ou CHF. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo de clientes do cliente. A página de configurações mostra um aviso quando faltam credenciais.
O pagamento foi feito, mas nenhum pedido foi criado: 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 que aparece nas configurações e se Transaction Payment Created está selecionado. Verifique se o Client ID e o Client Secret da conta desse pagamento ainda estão informados: o módulo precisa deles para verificar o pagamento. Ative o Debug Logging e veja o campo Log. O pedido também é criado quando o cliente volta à loja depois de pagar.
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 primeiro o Test Mode ou informe a chave dessa conta.
O webhook responde com erro: a Viva mostra a resposta da sua loja e reenvia webhooks com falha. verification_failed (HTTP 500) significa que não foi possível acessar a API da Viva para verificar o pagamento, ou que o pedido não pôde ser criado (por exemplo, o módulo está desativado). busy (HTTP 503) significa que o pedido estava sendo processado por outra requisição ao mesmo tempo. transaction_not_found (HTTP 404) significa que a transação não existe na conta desse pagamento, por exemplo por causa de credenciais incorretas. Eventos de pagamentos de outras lojas na mesma conta da Viva recebem a resposta ignored.
O cliente vê um erro ao escolher o Viva Wallet: consulte o campo Log na página do módulo. Um Client ID ou Client Secret incorreto exibe 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 cliente volta e vê We could not find your order. If you were charged, please contact us.: o código do pedido da Viva no endereço de retorno não é um pagamento desta loja, por exemplo porque a fonte de pagamento de outra loja aponta para cá. Verifique o Success URL e o Failure URL da fonte de pagamento.
O pedido fica em Viva Wallet payment on hold após o pagamento: leia as notas no bloco Viva Wallet payment (veja Status do pedido) e depois atenda 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 mostra Transaction ID not found. Cannot process refund.: o pedido não tem um pagamento confirmado na Viva, por exemplo após uma divergência de valor. Se necessário, reembolse o pagamento no painel da Viva.
Desinstalação
Desativar o módulo mantém todos os dados; apenas os tokens de acesso da Viva em cache são removidos. Para removê-lo, vá em Modules > Module Manager, abra o menu ao lado de VibeFox Viva Wallet Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Os tokens de acesso em cache e as chaves de webhook são sempre removidos. Se Delete Data on Uninstall estiver ativado, as configurações e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As tentativas de pagamento e os reembolsos da Viva e o status Viva Wallet payment on hold são sempre mantidos, então pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Pedidos existentes mantêm as suas notas de pagamento e os IDs de transação.
O Viva Wallet é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo Viva Wallet.