VibeFox Tap for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Moeda da loja: AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR ou USD. Para outras moedas, o método de pagamento fica oculto na finalização de compra.

Acesso à internet para o seu site: a Tap envia o resultado do pagamento a 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, apenas para o pop-up do Tap Checkout. 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 único 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_tap_payment_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > Tap Payments > 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 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).

6. Ative Enable / Disable e salve. Faça um teste com os cartões de teste da Tap e, depois, desmarque Test mode.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > Tap Payments. Acima dos campos, a página mostra Test mode is on: payments use your Tap test keys and no real money is charged. enquanto o modo de teste estiver ativado. Ela também avisa quando faltam as chaves do modo atual (nesse caso, o gateway não aparece na finalização de compra) e quando a moeda da loja não é aceita pela Tap. Na lista de métodos de pagamento, o Tap Payments aparece como pendente de configuração até que o modo atual tenha uma chave secreta (e, para o pop-up, uma chave publicável).

Ao salvar, uma chave com prefixo incorreto para o seu campo não é salva: é exibido um erro e o valor anterior é mantido. Por exemplo, uma chave de produção em um campo de teste é rejeitada.

Geral

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. Padrão: Tap Payments.

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: Use the test keys (no real money is charged). Pagamentos, consultas de status 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.

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 comerciante na Tap; só é necessário se a Tap tiver pedido que os pagamentos sejam direcionados a uma conta de comerciante específica.

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 nesta seção. Ela tem o formato https://your-site/wc-api/tap_p_webhook/. A URL é enviada com cada pagamento, então nada precisa ser configurado no painel da Tap. Basta garantir que ela esteja acessível pela internet (sem bloqueio de firewall, modo de manutenção ou autenticação HTTP). Cada notificação é verificada pela assinatura hashstring (HMAC-SHA256 com a chave secreta do modo do pagamento). Webhooks sem uma assinatura válida são rejeitados. Mesmo uma notificação assinada não é considerada confiável por si só: o plugin lê o pagamento novamente pela API da Tap antes de alterar o pedido. Sem um webhook funcionando, o pedido só é atualizado quando o cliente volta à loja depois de pagar.

Avançado

Debug log: Log payment events (WooCommerce → Status → Logs, source "wcp_tap_payment_gateway"). Erros são sempre registrados. O log nunca contém chaves, dados do cartão ou do cliente. Padrão: desativado.

Delete data on uninstall: Delete the gateway settings and logs when the plugin is deleted (order payment records are kept). Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão Tap Payments) e faz o pedido. No modo de teste, a finalização de compra exibe Test mode: no real payment will be made.

Tap payment page: o plugin cria uma cobrança na Tap (ou uma autorização, no modo Authorize only) pelo total do pedido na moeda do pedido, com a descrição Order # e o número do pedido, e envia o cliente para a página de pagamento da 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 vê The Tap payment could not be started. Please try again or choose another payment method., e o motivo é adicionado às notas do pedido.

Tap checkout popup: o cliente vai para a página de pagamento do pedido, 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.

Depois de pagar, o cliente volta para a página de pedido recebido. O pedido só é marcado como pago quando a Tap confirma: o plugin lê o pagamento pela API da Tap com a chave do modo do pagamento, verifica se ele se refere a este pedido e foi iniciado pela finalização de compra dele, e compara o valor e a moeda com os do pedido. O ID da Tap no endereço de retorno, sozinho, nunca marca um pedido como pago. O webhook faz a mesma verificação em segundo plano. Webhooks e retornos repetidos nunca alteram um pedido duas vezes (uma alteração por vez para cada pedido).

Se o pagamento ainda não tiver sido confirmado, a página de pedido recebido mostra 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. Para um pagamento autorizado, mostra Your payment has been authorized. We will process the order as soon as the payment is captured.

Se o pagamento tiver sido recusado ou abandonado, o pedido é marcado como Falhou e o cliente volta para a página Pay for order com a mensagem Your payment was not completed. Please try again or choose another payment method. (com o motivo informado pela Tap, quando houver). Um pagamento não concluído mostra The payment was not completed. You can try again below. O cliente pode pagar o pedido novamente a partir dessa página.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o WooCommerce High-Performance Order Storage (HPOS).

O plugin não possui 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

Pending payment: o cliente foi enviado para a Tap e ainda não pagou, ou a Tap ainda não confirmou o pagamento.

Processing: a Tap confirmou um pagamento capturado. Este é o status padrão do WooCommerce após o pagamento (pedidos apenas com produtos virtuais para download passam para Concluído). A nota do pedido mostra o valor, o ID da cobrança na Tap (chg_...), o método de pagamento e (no modo de teste) a indicação de que o pagamento é de teste. O ID da transação é o ID da cobrança na Tap.

On hold: o pagamento foi apenas autorizado e aguarda captura; ou o valor ou a moeda pagos não correspondiam ao pedido (Tap: amount/currency mismatch — manual review required.); ou um pagamento chegou depois que o pedido foi cancelado. A nota do pedido explica o motivo.

Failed: o pagamento foi recusado, abandonado, cancelado ou expirou. Somente um pedido que ainda aguarda pagamento é marcado como Falhou; uma tentativa com falha nunca altera um pedido pago, autorizado ou cancelado. O cliente pode pagar novamente.

Cancelled: a autorização foi anulada com Void Tap authorization, de modo que os valores reservados foram liberados.

Se chegar um segundo pagamento bem-sucedido para um pedido que já está pago, o pedido não é alterado novamente. Uma nota indica que se trata de um pagamento duplicado e pede que você o reembolse no painel da Tap. Um pagamento que se refere ao pedido, mas não foi iniciado pela finalização de compra dele, apenas é anotado.

Captura e anulação

No modo Authorize only, abra o pedido em espera e escolha em Order actions: Capture Tap payment captura o total do pedido; o pedido então passa a pago. Void Tap authorization libera os valores e cancela o pedido. Se a Tap recusar a ação, um erro é exibido e adicionado às notas do pedido. Se uma autorização for capturada diretamente no painel da Tap, o webhook marca o pedido como pago; os reembolsos desse pagamento devem ser feitos no painel da Tap.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via Tap Payments (o botão exibe o seu Title). Reembolsos totais e parciais são suportados para cobranças capturadas na Tap. O reembolso é enviado com a chave secreta do modo em que o pagamento foi feito, então essa chave precisa estar configurada. Um reembolso aceito pela Tap é adicionado às notas do pedido com o ID e o status do reembolso na Tap. Se a Tap recusar, o WooCommerce exibe o erro e nenhum reembolso é registrado. Reembolsos feitos no painel da Tap não aparecem no WooCommerce.

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 > Tap Payments. 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 inserir 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 único 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 Tap Payments não é exibido para os 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 o método de pagamento, marcado 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 Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados, e reembolsos, captura e anulação funcionam normalmente.

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

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 for o pop-up). Verifique se a moeda da loja (ou a moeda do pedido na página Pay for order) é uma de AED, BHD, EGP, EUR, GBP, JOD, KWD, OMR, QAR, SAR, USD. A página de configurações mostra um aviso para cada um desses problemas.

O pagamento foi feito, mas o pedido continua em Pending payment: o webhook não consegue alcançar o seu site. Verifique se a URL exibida nas configurações (/wc-api/tap_p_webhook/) está acessível pela internet (sem firewall, modo de manutenção ou autenticação HTTP) e consulte WooCommerce > Status > Logs, origem wcp_tap_payment_gateway. O pedido também é atualizado 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. Preencha-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.

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

O pedido está On hold: leia a nota do pedido. O pagamento foi apenas autorizado (capture-o pelas ações do pedido), o valor ou a moeda pagos não correspondiam ao pedido, ou o pagamento chegou depois que o pedido foi 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 a nota disser que nenhuma cobrança capturada na Tap foi encontrada, reembolse o pagamento no painel da Tap.

Hooks para desenvolvedores: os filtros tap_p_supported_currencies, tap_p_currency_decimals, tap_p_charge_payload, tap_p_icon, tap_p_checkout_sdk_url e tap_p_payment_page_hosts estão disponíveis.

O bloco de licença exibe 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.

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, as demais opções do plugin e os logs só são removidos se Delete data on uninstall estiver ativado. Caso contrário, permanecem para uma reinstalação posterior. Os pedidos existentes mantêm suas notas de pagamento, IDs da Tap e IDs de transação.

Tap Payments é uma marca registrada de seu respectivo proprietário. Este plugin não é afiliado nem endossado pela Tap Payments.