VibeFox Tap 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: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR ou USD. Para carrinhos em outras moedas, o método de pagamento fica oculto na finalização de compra.

Acesso à Internet para a sua loja: a Tap envia o resultado do pagamento para um webhook na sua loja, por isso o site precisa estar acessível pela Internet. A URL do webhook é enviada com cada pagamento; nada precisa ser configurado no painel da Tap.

Conta na Tap: você precisa das chaves de API do seu painel da Tap (goSell, credenciais de API). As chaves de teste começam com pk_test_ / sk_test_, e as de produção com pk_live_ / sk_live_. A chave secreta é sempre necessária; a chave publicável, somente para o pop-up. Os métodos de pagamento oferecidos (mada, KNET, Benefit e outros) e a verificação de domínio do Apple Pay são configurados na sua conta da Tap.

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 Tap Payments mais tarde na lista de módulos e clique em Configure.

3. Insira a sua chave de licença VibeFox em License key, no bloco de licença no topo da página Configure, e clique em Activate (veja Chave de licença).

4. Insira as suas chaves de teste e de produção da Tap, escolha a ação de pagamento, o tipo de finalização de compra e o idioma da página da Tap (veja Configuração).

5. Ative Enable / Disable e clique em Save. Faça testes com os cartões de teste da Tap e depois desative Test mode.

Ao ser instalado, o módulo cria dois status de pedido: Tap payment authorized e Tap payment on hold. O PrestaShop disponibiliza um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode restringi-lo em Payment > Preferences.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Tap Payments > Configure. Cada seção tem o seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Test mode is on: payments use your Tap test keys and no real money is charged. ou Live mode: real payments are accepted. Ela também avisa quando faltam as chaves do modo atual (o método de pagamento então não aparece na finalização de compra) e quando a moeda padrão da loja não é oferecida com a Tap.

Ao salvar, uma chave com prefixo errado para o seu campo não é salva: o valor anterior é mantido, as demais configurações são salvas e aparece uma mensagem como Test secret key was not saved: a Tap key for this field starts with "sk_test_".. Por exemplo, uma chave de produção em um campo de teste é recusada. Um Title vazio não é aceito: a página mostra Enter a title for the payment method. e nada é salvo.

Tap Payments

O título da seção também mostra TEST ou LIVE para o modo atual.

Enable / Disable: Enable Tap Payments ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento exibido na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Tap Payments. Obrigatório.

Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay with Visa, Mastercard, mada, KNET, Benefit, Apple Pay or Google Pay.

Chaves de API da Tap

Encontre as suas chaves no painel da Tap (goSell, credenciais de API). As chaves de teste começam com pk_test_ / sk_test_, e as de produção com pk_live_ / sk_live_.

Test mode: usa as chaves de teste; nenhum dinheiro real é cobrado. Pagamentos, consultas de status, capturas e reembolsos sempre usam as chaves do modo em que o pagamento foi feito; assim, um pagamento de teste continua sendo consultado e reembolsado com a chave de teste mesmo depois de você mudar para produção. Padrão: ativado. Enquanto estiver ativado, os clientes veem Test mode: no real payment will be made. abaixo do método de pagamento.

Test publishable key: começa com pk_test_. Necessária para o pop-up.

Test secret key: começa com sk_test_.

Live publishable key: começa com pk_live_. Necessária para o pop-up.

Live secret key: começa com sk_live_.

Merchant ID: opcional. O seu ID de merchant na Tap; só é necessário se a Tap pediu que os pagamentos fossem direcionados a uma conta de merchant específica.

As chaves secretas salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente se quiser alterar a chave. As chaves publicáveis são públicas e continuam visíveis.

Clear saved secrets: marque uma chave secreta e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

Pagamento

Payment action: o que acontece com o dinheiro quando o cliente paga.

Checkout type: onde o cliente paga.

Tap page language: English (padrão) ou Arabic.

Notificações de pagamento (webhook)

A Tap envia o resultado do pagamento para a URL exibida em Webhook URL nesta seção. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_tap_payment_gateway/webhook, possivelmente com um código de idioma como /en/. A URL é enviada com cada pagamento, portanto nada precisa ser configurado no painel da Tap. Apenas certifique-se de que ela pode ser acessada pela Internet (sem bloqueio por firewall ou autenticação HTTP). Cada notificação é verificada pela assinatura hashstring (HMAC-SHA256 com a chave secreta do modo em que o pagamento foi feito). Webhooks sem assinatura válida são rejeitados. Mesmo uma notificação assinada não é considerada confiável por si só: o módulo consulta o pagamento novamente pela API da Tap antes de criar ou alterar o pedido. Sem um webhook funcionando, o pedido só é criado quando o cliente volta à loja depois de pagar.

Avançado

Debug log: registra os eventos de pagamento em logs/tap_p_debug.log.php, na pasta do módulo. O arquivo não pode ser lido pela web. Erros e avisos são sempre registrados; ative esta opção para registrar também cada evento de pagamento. O log nunca contém chaves, dados de cartão ou de clientes. 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, desinstalar o módulo remove as configurações do gateway e o log. Os registros de pagamento dos pedidos são mantidos. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Tap Payments) e confirma o pedido. Nesse momento, ainda não existe pedido.

Tap payment page: o módulo cria uma cobrança na Tap (ou uma autorização no modo Authorize only) pelo total do carrinho na moeda do carrinho, com a descrição Cart # e o número do carrinho, e envia o cliente para a página de pagamento da Tap. Nome, e-mail e telefone do cliente são enviados à Tap. Lá, o cliente escolhe um cartão, mada, KNET, Benefit, Apple Pay ou Google Pay (conforme ativados na sua conta da Tap) e paga. Se a Tap não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com The Tap payment could not be started. Please try again or choose another payment method. e o motivo é registrado no log.

Tap checkout popup: o cliente vai à página Tap payment do módulo, onde o formulário de pagamento da Tap é aberto. A página também mostra o link Pay on the Tap payment page instead. Se a janela for fechada, o botão Pay now a abre novamente. Se o formulário não puder ser carregado, o cliente é orientado a usar a página de pagamento da Tap. Recarregar a página reutiliza a mesma tentativa de pagamento.

Depois de pagar, o cliente volta à sua loja. O pedido só é marcado como pago quando a Tap confirma: o módulo lê o pagamento pela API da Tap com a chave do modo do pagamento, verifica se ele se refere a este carrinho e foi iniciado pela finalização de compra dele, e compara o valor e a moeda com os do carrinho. O ID da Tap no endereço de retorno, sozinho, nunca cria um pedido. O webhook faz a mesma verificação em segundo plano. Em seguida, o pedido é criado e o cliente vê a página padrão de confirmação do pedido. Para um pagamento autorizado, a página mostra Your payment has been authorized. We will process the order as soon as the payment is captured.; para um pedido em espera, mostra Your payment is being reviewed. We will contact you if anything else is needed.

Se a Tap ainda não tiver confirmado o pagamento quando o cliente voltar, aparece uma página Payment confirmation com We have not received the payment confirmation from Tap yet. If you completed the payment, the order will be updated automatically in a few minutes — there is no need to pay again. e os botões Check again e Back to checkout. O webhook cria o pedido assim que chegar.

Se o pagamento for recusado, abandonado ou cancelado, nenhum pedido é criado. O cliente volta à finalização de compra com Your payment was not completed. Please try again or choose another payment method. (com o motivo da Tap, quando a Tap informa um). Um pagamento não concluído mostra The payment was not completed. You can try again or choose another payment method. O carrinho é mantido e pode ser pago novamente.

Outras mensagens na finalização de compra: Tap does not accept payments in, seguido da moeda, quando a moeda do carrinho não é suportada, e The order total must be greater than zero to pay with Tap.

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 não tem cartões salvos nem tokenização, assinaturas, nem campos de cartão incorporados à sua finalização de compra. Capture Tap payment sempre captura o total do pedido; a captura parcial não é suportada.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado para a Tap e não pagou, ou a Tap ainda não confirmou o pagamento. Existe apenas o carrinho.

Payment accepted: a Tap confirmou um pagamento capturado. O pagamento é registrado com o ID da cobrança na Tap (chg_...) como ID da transação, e uma nota mostra o valor, o ID da cobrança, o método de pagamento e, no modo de teste, que o pagamento é de teste.

Tap payment authorized: o pagamento foi apenas autorizado e aguarda captura ou cancelamento.

Tap payment on hold: o valor ou a moeda pagos eram diferentes do carrinho (Tap: amount/currency mismatch — manual review required.), ou um pagamento chegou depois que o pedido havia sido cancelado. A nota explica o motivo. Verifique o pedido e processe-o, ou reembolse o pagamento.

Canceled: a autorização foi cancelada com Void Tap authorization, então os valores reservados foram liberados.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Uma tentativa malsucedida nunca altera um pedido pago, autorizado ou cancelado. Se chegar um segundo pagamento bem-sucedido para um pedido que já está pago, o pedido não é alterado. Uma nota informa que se trata de um pagamento duplicado e pede que ele seja reembolsado no painel da Tap. Um pagamento que se refere ao carrinho, mas não foi iniciado pela finalização de compra dele, apenas é anotado.

Bloco de pagamento da Tap

A página do pedido mostra um bloco Tap payment com o ID da Tap, a autorização e a cobrança, o modo (um selo Test mode para pagamentos de teste), o status e o método de pagamento, Charged / refunded, o histórico de reembolsos, as tentativas de pagamento do carrinho e as Payment notes do pedido. Os botões do bloco funcionam na própria página do pedido; é preciso ter permissão para editar pedidos, não acesso às configurações do módulo.

Captura e cancelamento

No modo Authorize only, abra o pedido no status Tap payment authorized. Capture Tap payment (com o total do pedido no botão) captura o total do pedido após a pergunta Capture the reserved funds of this order through Tap?; o pedido passa então para Payment accepted. Void Tap authorization pergunta Release the reserved funds? The order will be canceled., libera os valores e coloca o pedido em Canceled. Se a Tap rejeitar a ação, um erro é exibido no bloco e adicionado às notas. Se uma autorização for capturada diretamente no painel da Tap, o webhook marca o pedido como pago; reembolsos desse pagamento devem ser feitos no painel da Tap.

Reembolsos

No bloco Tap payment, informe o valor (é preenchido o valor ainda não reembolsado), opcionalmente um motivo, e clique em Refund via Tap. Confirme a pergunta Refund this amount through Tap? This cannot be undone. Reembolsos totais e parciais são suportados para cobranças da Tap capturadas. Você pode reembolsar até o valor e a moeda que a Tap efetivamente cobrou, mesmo que o pedido tenha sido editado depois. O reembolso é enviado com a chave secreta do modo em que o pagamento foi feito, por isso essa chave precisa estar configurada. Um reembolso aceito pela Tap é adicionado ao histórico de reembolsos e às notas, com o ID e o status do reembolso na Tap. Se a Tap o recusar, o bloco mostra o erro e nenhum reembolso é registrado. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não altera o status. Para um pedido autorizado, os reembolsos ficam disponíveis depois que a autorização é capturada. Um pedido em espera após divergência de valor ou moeda é reembolsado no painel da Tap.

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 Tap. Reembolsos feitos no painel da Tap não aparecem no PrestaShop.

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 Tap Payments é o primeiro bloco em Modules > Module Manager > VibeFox Tap Payments > Configure, acima das configurações. Cole 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-tap e o link Manage licenses and domains in your account, que abre a sua conta do 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 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 dela. Libere a vaga na sua conta do vibefox.net.

Sem uma chave ativa, o Tap Payments 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. 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 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: pagamentos já iniciados continuam sendo confirmados, e reembolsos, captura e cancelamento continuam funcionando.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado de novo automaticamente 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

O Tap Payments 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 uma chave secreta (e uma chave publicável quando Checkout type é o pop-up). Verifique se a moeda do carrinho é uma de AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR ou USD. Em Payment > Preferences, verifique se o módulo está permitido para a moeda do carrinho, o país do cliente e o grupo do cliente. A página de configurações exibe um aviso para chaves ausentes e para uma moeda da loja não suportada.

O pagamento foi feito, mas nenhum pedido foi criado: o webhook não consegue alcançar a sua loja. Verifique se a URL exibida em Webhook URL está acessível pela Internet (sem firewall ou autenticação HTTP) e ative o Debug log para ver as respostas no campo Log. O pedido também é criado quando o cliente volta da Tap.

Webhook answers invalid signature: a notificação não foi assinada com a chave secreta do modo do pagamento. Verifique as chaves secretas nas configurações.

Webhook answers gateway not configured: a chave secreta do modo do pagamento (teste ou produção) está vazia. Informe-a.

Webhook answers verification failed: não foi possível acessar a API da Tap para verificar o pagamento. A Tap tenta o webhook novamente mais tarde.

Webhook answers order not found: a notificação indica um carrinho que não tem nenhuma tentativa de pagamento da Tap nesta loja.

Webhook answers busy, retry later or order could not be updated, retry later: o pedido estava sendo confirmado 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 Tap tenta o webhook novamente. Consulte o campo Log para ver o motivo.

Uma chave não é salva: a chave deve começar com o prefixo do seu campo: pk_test_, sk_test_, pk_live_ ou sk_live_.

O cliente vê The Tap payment could not be started: consulte o campo Log na página do módulo. Uma chave incorreta ou uma requisição recusada são registradas ali.

O cliente vê We could not match this payment to an order: o pagamento não pertence a este carrinho ou não foi iniciado pela finalização de compra dele. Se o dinheiro foi cobrado, verifique o pagamento no painel da Tap.

O pedido está em Tap payment on hold: leia as notas no bloco Tap payment. O valor ou a moeda pagos não correspondiam ao carrinho, ou o pagamento chegou depois que o pedido havia sido cancelado.

O reembolso falha com uma mensagem sobre o modo: o pagamento foi feito no modo de teste ou de produção, e nenhuma chave secreta está configurada para esse modo. Informe-a e tente novamente. Se o bloco disser que nenhuma cobrança capturada da Tap foi encontrada, reembolse o pagamento no painel da Tap.

Hooks para desenvolvedores: os hooks actionWcpTapChargePayload, actionWcpTapSupportedCurrencies e actionWcpTapCurrencyDecimals permitem que um desenvolvedor altere a requisição de pagamento, as moedas suportadas e as casas decimais das moedas.

Desinstalação

Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Tap Payments e escolha Uninstall. A chave de licença e o status de 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 tentativas de pagamento e os reembolsos da Tap e os status de pedido Tap payment authorized e Tap payment on hold são sempre mantidos, de modo que pedidos pagos antes ainda podem ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

O Tap Payments é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pelo Tap Payments.