VibeFox Tpay for WooCommerce — Ajuda
Requisitos
WordPress: 5.8 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior. A extensão OpenSSL e conexões HTTPS de saída para secure.tpay.com são necessárias para a verificação da assinatura JWS das notificações.
Moeda da loja: somente złoty polonês (PLN). O Tpay liquida em PLN e a sua Open API não tem campo de moeda, então o método de pagamento é ocultado quando a loja (ou o pedido a ser pago) usa outra moeda.
Acesso à internet para o seu site: o Tpay envia as notificações de pagamento para a sua loja, então o endereço de notificação precisa estar acessível pela internet (não bloqueado pelo modo de manutenção, por um firewall ou pela autenticação HTTP).
Conta no Tpay: você precisa destes valores do painel do comerciante no Tpay: o Merchant ID (o ID da sua conta no Tpay), as chaves da Open API Client ID e Client secret (Integration, API) e o código de segurança (Settings, Notifications). As chaves de sandbox vêm de uma conta de sandbox separada no Tpay.
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_tpay_payment para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Tpay > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Digite as chaves de Sandbox e as chaves de Produção (veja Configuração). No painel do Tpay não é preciso definir nada além do código de segurança: o endereço de notificação é enviado em cada transação.
6. Ative Enable/Disable, teste um pagamento no modo sandbox e, em seguida, desmarque Sandbox mode para aceitar pagamentos reais.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Tpay. Acima dos campos, a página mostra Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. enquanto o modo sandbox estiver ativado. Ela avisa quando as chaves do modo atual estão incompletas (nesse caso o Tpay não aparece na finalização de compra), quando a moeda da loja não é PLN e quando a extensão PHP OpenSSL está ausente enquanto a verificação JWS está ativada (os pagamentos não seriam confirmados). Na lista de métodos de pagamento, o Tpay aparece como pendente de configuração até que as chaves do modo atual sejam informadas. Espaços colados junto ao Merchant ID ou ao Client ID são removidos ao salvar.
Geral
Enable/Disable: Enable Tpay payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o título do método de pagamento exibido aos clientes na finalização de compra. Padrão: Tpay.
Description: a descrição do método de pagamento exibida aos clientes na finalização de compra. Padrão: Pay with BLIK, online bank transfer or card on the secure Tpay page.
Sandbox mode: Use the Tpay sandbox (test payments, no real money). O modo sandbox usa as chaves de Sandbox e a API de sandbox do Tpay. Desative-o para aceitar pagamentos reais com as chaves de Produção. Os reembolsos sempre são enviados ao ambiente em que o pedido foi pago. Padrão: ativado.
Chaves de produção
Onde encontrá-las: no painel do comerciante no Tpay, em Integration, API (chaves da Open API: Client ID e Secret); o Merchant ID é o ID da sua conta no Tpay; o código de segurança fica em Settings, Notifications.
Merchant ID: o ID da sua conta no Tpay (dígitos). O Tpay o envia em cada notificação.
Client ID: o Open API Client ID.
Client secret: o Open API Client secret.
Security code: usado para verificar a soma de verificação MD5 das notificações do Tpay.
Chaves de sandbox
O sandbox é uma conta de teste separada no Tpay, com as próprias chaves (veja a documentação da API do Tpay). Elas são usadas somente enquanto Sandbox mode estiver ativado.
Sandbox Merchant ID: o Merchant ID da conta de sandbox.
Sandbox Client ID: o Open API Client ID da conta de sandbox.
Sandbox Client secret: o Open API Client secret da conta de sandbox.
Sandbox Security code: o código de segurança das notificações da conta de sandbox.
Notificações de pagamento
O Tpay confirma os pagamentos no endereço mostrado nesta seção. Ele tem a forma https://your-site/wc-api/wc_tp_payment/. O endereço é enviado automaticamente em cada transação; não é preciso configurar nada no painel do Tpay além do código de segurança. Um pedido só é marcado como pago depois de uma notificação com soma de verificação e assinatura válidas e com valor correspondente. O Tpay repete uma notificação até que a sua loja a aceite.
Assinatura JWS: Also verify the X-JWS-Signature of notifications with the Tpay certificate (recommended). Requer a extensão PHP OpenSSL e conexões HTTPS de saída para secure.tpay.com. A soma de verificação MD5 é sempre verificada. Padrão: ativado.
Avançado
Debug log: Log payment events. Somente eventos técnicos (sem chaves e sem dados de clientes) em WooCommerce > Status > Logs, origem wcp_tpay_payment. Padrão: desativado.
Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted. Desativar o plugin nunca remove nada. Os pedidos e os dados de pagamento do Tpay sempre são mantidos. Padrão: desativado.
As configurações da versão 1.0 são transferidas automaticamente: as chaves usadas com o modo de teste ativado passam a ser as chaves de Sandbox.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Tpay) e faz o pedido. No modo sandbox, a finalização de compra mostra Sandbox mode — no real money is charged. O plugin cria uma transação no Tpay pelo total do pedido em PLN, com a descrição Order # e o número do pedido, envia o nome, o e-mail, o endereço e o telefone do cliente e redireciona o cliente para a página de pagamento do Tpay. A página é exibida em polonês, inglês ou ucraniano, conforme o idioma do site (os demais idiomas recebem inglês). Lá o cliente escolhe BLIK, uma transferência bancária, um cartão ou outro método habilitado na sua conta do Tpay, e paga.
O pedido só é marcado como pago depois que o Tpay confirma. O Tpay envia uma notificação para a sua loja; o plugin verifica a soma de verificação MD5 com o código de segurança, o Merchant ID e (quando ativada) a assinatura JWS, e depois o valor: ele deve ser igual ao valor solicitado para esta tentativa de pagamento e ao total do pedido, e o valor pago não pode ser menor. Notificações sem soma de verificação ou assinatura válidas são rejeitadas.
Depois de pagar, o cliente volta à página de pedido recebido. Apenas o retorno não marca o pedido como pago. Se a notificação ainda não tiver chegado, a página consulta a API do Tpay sobre o status da transação (no máximo a cada 10 segundos) e aplica as mesmas verificações. Enquanto o pagamento não for confirmado, a página mostra Tpay has not confirmed your payment yet. If you have paid, refresh this page in a moment. If the payment did not go through, you can try again: com um link Pay again. Quando o Tpay informa um pagamento malsucedido, a página mostra Tpay reports that the payment did not go through. You can try again: com o mesmo link. Se o pagamento falhar na página do Tpay, o Tpay devolve o cliente à página Pay for order do mesmo pedido.
Cada tentativa de pagamento tem sua própria referência. Quando o cliente paga novamente, as transações anteriores não pagas do pedido no Tpay são canceladas; um pagamento que já foi concluído por um link anterior continua sendo aceito. O mesmo cancelamento acontece quando um pedido não pago é cancelado, por exemplo pelo tempo limite de reserva de estoque do WooCommerce.
Se o Tpay não conseguir iniciar o pagamento, o cliente vê The Tpay payment could not be started. Please try again or choose another payment method. e o motivo é registrado no log.
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 funciona somente em PLN. Não há seleção de banco nem de código BLIK na loja (o cliente escolhe na página do Tpay), não há cartões salvos, assinaturas, botões de Apple Pay ou Google Pay na loja nem simuladores de parcelamento.
Pedidos e reembolsos
Status do pedido
Pending payment: a transação no Tpay foi criada e o pagamento ainda não foi confirmado. A nota do pedido mostra a transação do Tpay e o ambiente.
Processing: o Tpay confirmou o pagamento. É o status padrão do WooCommerce após o pagamento (pedidos com apenas produtos digitais para download passam para Concluído). A nota informa se o pagamento foi confirmado pela notificação ou pela verificação de status e mostra qualquer pagamento excedente. O ID da transação é o título da transação no Tpay (TR-...).
On hold: chegou um pagamento, mas o valor era diferente do solicitado ou do total do pedido, apenas uma parte foi paga, ou o pedido havia sido cancelado. A nota do pedido explica isso. Verifique o pagamento no painel do Tpay e conclua ou reembolse o pedido.
Failed: o Tpay informou que o pagamento falhou. Somente um pedido pendente é marcado como Falhou. O cliente pode pagar novamente.
Se o Tpay informar outro pagamento para um pedido que já está pago ou reembolsado, o pedido não é alterado; uma nota pede que você reembolse o pagamento extra no painel do Tpay, se necessário. Uma contestação (chargeback) informada pelo Tpay acrescenta uma nota.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Tpay (o botão mostra o seu Title). Reembolsos totais e parciais são aceitos para pedidos com pagamento recebido pelo Tpay; para pedidos não pagos, o botão não aparece. O reembolso é enviado ao ambiente (sandbox ou produção) em que o pedido foi pago, por isso as chaves desse ambiente precisam estar configuradas. O reembolso só conta como concluído quando o Tpay o confirma; um reembolso recusado ou não confirmado pelo Tpay é exibido como erro e não é registrado no WooCommerce. Um reembolso bem-sucedido é adicionado às notas do pedido, junto com o motivo que você informou (o motivo não é enviado ao Tpay).
Reembolsos feitos no painel do comerciante no Tpay não são adicionados automaticamente ao 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 > Tpay. 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 Tpay 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 que estiverem conectados 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 os reembolsos funcionam.
Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte precisam de renovação. O status é verificado novamente de forma automática em segundo plano.
Solução de problemas
O Tpay não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se as quatro chaves do modo atual foram informadas (Merchant ID, Client ID, Client secret, Security code). Verifique se a moeda da loja (ou a moeda do pedido na página Pay for order) é PLN. 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 Tpay não conseguiu entregar a notificação ou ela foi rejeitada. Ative o Debug log e veja WooCommerce > Status > Logs, origem wcp_tpay_payment. As causas mais comuns são um código de segurança ou Merchant ID incorretos para o modo atual, um endereço de notificação bloqueado (modo de manutenção, firewall, autenticação HTTP) ou um servidor sem OpenSSL ou sem HTTPS de saída para a verificação JWS. A página de pedido recebido também verifica o status quando o cliente retorna.
Notification answered FALSE - invalid checksum: o Merchant ID ou o código de segurança nas configurações não corresponde à conta do Tpay (sandbox ou produção) do pagamento.
Notification answered FALSE - invalid JWS signature: a assinatura não pôde ser verificada, por exemplo porque o OpenSSL está ausente ou o certificado do Tpay não pode ser baixado. Corrija o servidor ou, se necessário, desative JWS signature; a soma de verificação MD5 continua sendo verificada.
O pedido está On hold: leia a nota do pedido. O valor pago não correspondeu ao pedido, ou o pagamento chegou para um pedido cancelado. Verifique o pagamento no painel do Tpay e conclua ou reembolse o pedido.
O cliente viu The Tpay payment could not be started: as chaves do modo atual estão incorretas ou o Tpay recusou a solicitação. O log mostra o erro do Tpay.
O reembolso falha: se a mensagem disser que as chaves estão faltando, informe as chaves do ambiente em que o pedido foi pago. Se o Tpay não confirmou o reembolso, verifique a transação no painel do comerciante no Tpay antes de tentar de novo.
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 para o 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 de licença deste plugin são sempre removidos, assim como os tokens de acesso em cache do Tpay e os certificados. As configurações do gateway e os logs 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 as notas de pagamento, os dados de transação do Tpay e os IDs de transação.
O Tpay é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pelo Tpay.