VibeFox Tranzila 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: ILS, USD, EUR ou GBP. Para outras moedas, o método de pagamento fica oculto na finalização de compra.
Terminal Tranzila: você precisa do nome do terminal. A senha do terminal (TranzilaPW) é necessária para o handshake e para os reembolsos pelo WooCommerce. Alguns terminais também exigem uma senha de crédito separada (CreditPass) para reembolsos. O nome do terminal e as senhas são fornecidos pela Tranzila: veja as configurações do seu terminal ou peça ao suporte da Tranzila. A Tranzila não tem sandbox público. Para testes, a Tranzila fornece um terminal de teste separado; informe o nome dele como nome do terminal.
IP real do visitante: as notificações de pagamento são verificadas pelo endereço IP do servidor da Tranzila. Se o seu site estiver atrás de um proxy ou CDN, como o Cloudflare, o servidor web deve repassar ao PHP o IP real do visitante (REMOTE_ADDR).
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_tranzila_payment_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Tranzila > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Preencha o Terminal name (supplier) e, se usar o handshake ou os reembolsos, a Terminal password (TranzilaPW).
6. Mantenha Notifications ativado e confira o Trusted IP: ele deve listar os endereços IP dos quais a Tranzila envia as notificações. Confirme a lista com o suporte da Tranzila.
7. Recomendado: ative o handshake no terminal da Tranzila, permita lá o IP do seu servidor e depois ative o Handshake no plugin.
8. Ative o Enable/Disable e teste um pagamento com o terminal de teste da Tranzila.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Tranzila. Acima dos campos, a página avisa quando o nome do terminal está vazio (o método de pagamento fica oculto na finalização de compra), quando as notificações estão desativadas ou o Trusted IP está vazio (pedidos pagos são então colocados em espera para revisão manual), quando o handshake está ativado sem senha do terminal (a página de pagamento não pode ser aberta) e quando a moeda da loja não é suportada. Ao salvar, um nome de terminal inválido ou uma entrada inválida no Trusted IP não é salvo: a página mostra um erro e o valor anterior é mantido. Números fora da faixa permitida são corrigidos para o valor permitido mais próximo.
General
Enable/Disable: Enable Tranzila Payment Gateway liga ou desliga o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Padrão: Credit Card (Tranzila).
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with your credit card on the Tranzila payment page.
Terminal
Terminal name (supplier): o nome do seu terminal Tranzila, por exemplo myshop. Somente letras, números, «-» e «_». Enquanto não for preenchido, o método de pagamento não aparece na finalização de compra. Para testes, informe o nome do seu terminal de teste da Tranzila.
Terminal password (TranzilaPW): a senha de API do terminal. É necessária para o handshake e para os reembolsos pelo WooCommerce.
Refund password (CreditPass): somente se o seu terminal exigir uma senha separada para transações de crédito (reembolsos). Caso contrário, deixe em branco.
Payment page
Payment page version: a página da Tranzila exibida no iframe.
Payment page language: o idioma da página da Tranzila: Site language, Hebrew, English, Russian, Spanish, German, French ou Japanese. Padrão: Hebrew. A opção Site language usa o idioma da localidade do WordPress do visitante quando ele é um destes idiomas; caso contrário, English.
iFrame width (px): de 300 a 1200. Padrão: 600. Em telas pequenas, o quadro nunca é mais largo que a página.
iFrame height (px): de 400 a 1500. Padrão: 650.
Max installments: o número máximo de parcelas (tashlumim) que o cliente pode escolher na página de pagamento, até 36. 0 ou 1 significa sem parcelamento. Padrão: 0. O terminal precisa estar autorizado a processar parcelamentos.
Handshake: Lock the amount with a handshake token (recommended). Antes de abrir a página de pagamento, a loja pede à Tranzila um token único vinculado ao valor do pedido, para que o valor não possa ser alterado no navegador. Exige a senha do terminal, o handshake ativado no terminal da Tranzila e o IP do seu servidor permitido nele. Padrão: desativado.
Payment confirmation
As notificações da Tranzila não são assinadas. Um pedido só é marcado como pago quando a notificação vem de um Trusted IP e sua chave de pedido, terminal, valor e moeda correspondem ao pedido. Com o handshake ativado, o token também precisa corresponder à página de pagamento do pedido. O retorno do cliente da página de pagamento nunca marca um pedido como pago.
Notifications: Confirm payments automatically with Tranzila notifications (notify URL). Padrão: ativado. A URL de notificação é enviada à Tranzila em cada pagamento, por isso você não precisa informá-la no terminal da Tranzila. Ela tem este formato: https://your-site/wc-api/tranzila_p_callback/ e aparece abaixo do campo. Com as notificações desativadas, um cliente que volta de uma página de pagamento bem-sucedida deixa o pedido em espera, e você confirma o pagamento manualmente depois de conferi-lo no terminal da Tranzila.
Trusted IP: os endereços IP ou faixas CIDR dos servidores da Tranzila que enviam notificações, separados por vírgulas. Padrão: 80.244.170.7. Confirme a lista atual com o suporte da Tranzila. Notificações de outros endereços são rejeitadas. Se o campo estiver vazio, as notificações não podem ser verificadas: um pagamento bem-sucedido informado coloca o pedido em espera para revisão manual, e uma recusa informada não altera o pedido.
Advanced
Debug log: Log payment page, notification and refund events grava em WooCommerce > Status > Logs, origem wcp_tranzila_payment_gateway. Erros são sempre registrados, mesmo com esta opção desativada. Senhas, tokens e dados de clientes nunca são gravados. Padrão: desativado.
Delete data on uninstall: Delete the settings, logs and Tranzila order data when the plugin is deleted. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Credit Card (Tranzila)) e clica em Continue to payment. O pedido é criado com o status Aguardando pagamento, e o cliente vai para a página de pagamento do pedido da sua loja. Lá a página de pagamento da Tranzila abre em um iframe, com o total do pedido na moeda do pedido, os dados de faturamento e uma lista resumida dos produtos. A página diz Enter your card details on the secure Tranzila payment page below. If it does not load, click "Proceed to payment". O link Choose another payment method fica abaixo do quadro. Se o parcelamento for permitido, o cliente escolhe o número de parcelas na página da Tranzila.
Após um pagamento bem-sucedido, a Tranzila devolve o cliente e toda a janela passa para a página de pedido recebido da sua loja. O pedido só é marcado como pago quando a Tranzila confirma com uma notificação. Até lá, a página mostra Your payment is being confirmed by Tranzila. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se o pedido estiver em espera para revisão, a página mostra Your payment is being reviewed by the store. You will receive an e-mail once it is confirmed.
Se o pagamento for recusado ou cancelado, o cliente volta à página de pagamento do pedido com a mensagem The payment was not completed. You have not been charged — please try again or choose another payment method. Quando a Tranzila informa um código de resposta, o motivo e o código são acrescentados, por exemplo que o cartão está vencido. O cliente pode pagar de novo ou escolher outro método de pagamento.
Se a página de pagamento não puder ser aberta, por exemplo quando o handshake falha, o cliente vê uma mensagem curta como Could not connect to Tranzila. Please try again in a moment. e o link 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 Finalização de compra e na página Pay for order. Na página Pay for order ele é oferecido quando a moeda do pedido é suportada. É compatível com o WooCommerce High-Performance Order Storage (HPOS).
O plugin aceita apenas pagamentos únicos com cartão, na página da Tranzila. Não há cartões ou tokens salvos, assinaturas, autorização e captura separadas (J5), botões próprios de Bit, Apple Pay ou Google Pay (o que a sua página de pagamento da Tranzila oferecer é exibido dentro do iframe) nem faturas da Tranzila.
Pedidos e reembolsos
Order statuses
Pending payment: o cliente foi enviado à página de pagamento e ainda não pagou, ou a notificação da Tranzila ainda não chegou.
Processing or Completed: o pagamento foi confirmado por uma notificação verificada. O WooCommerce define Em processamento, ou Concluído para pedidos que não precisam de envio. A nota do pedido mostra o valor, a transação da Tranzila e o número de autorização, além do número de parcelas, se houver. O ID da transação é o índice de transação da Tranzila.
On hold: o pagamento foi recebido, mas não foi aceito automaticamente: o valor, a moeda ou o token do handshake não correspondiam ao pedido; a notificação não pôde ser verificada porque o Trusted IP está vazio; ou as notificações estão desativadas e o cliente voltou de uma página de pagamento bem-sucedida. A nota do pedido explica o motivo. Confira o pagamento no terminal da Tranzila e altere o status manualmente.
Failed: a Tranzila informou um pagamento recusado para um pedido pendente. A nota mostra o código de resposta e o seu significado. Um pedido já pago nunca é alterado para Failed.
Se um pagamento chegar para um pedido cancelado, o pedido é reaberto com uma nota pedindo que você confira o estoque antes do envio. Se o cliente trocou de método de pagamento na página Pay for order, mas pagou em uma página da Tranzila que ainda estava aberta, o método de pagamento do pedido volta para a Tranzila. Se um segundo pagamento chegar para um pedido que já está pago, concluído ou reembolsado, o pedido não muda. Uma nota pede que você o verifique e reembolse a duplicata no terminal da Tranzila. Notificações repetidas da mesma transação são ignoradas.
Refunds
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Credit Card (Tranzila) (o botão exibe o título do método de pagamento). Há suporte a reembolsos totais e parciais. O reembolso é feito como uma transação de crédito da Tranzila sobre o pagamento original. O botão fica disponível quando a senha do terminal está preenchida e o pedido tem uma transação da Tranzila confirmada com número de autorização. Um reembolso bem-sucedido é adicionado às notas do pedido, junto com a transação de crédito da Tranzila.
Se a Tranzila não aceitar o reembolso, o WooCommerce exibe o erro, por exemplo Tranzila declined the refund com o código, e nenhum reembolso é registrado. Um pedido pago em um terminal diferente do configurado agora (por exemplo, um terminal de teste) não pode ser reembolsado pelo WooCommerce; reembolse-o nesse terminal da Tranzila. Reembolsos feitos no terminal da Tranzila não são informados à loja. Se necessário, crie um reembolso manual no WooCommerce sem usar o botão da Tranzila.
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 > Tranzila. 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 na sua conta em vibefox.net.
Sem uma chave ativa, a Tranzila não é exibida 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. Gerentes da loja 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. 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 exigem renovação. O status é verificado novamente, automaticamente, em segundo plano.
Solução de problemas
Tranzila does not appear at checkout: confira se a licença está ativa, se o Enable/Disable está ligado, se o Terminal name (supplier) está preenchido e se a moeda da loja (na página Pay for order, a moeda do pedido) é ILS, USD, EUR ou GBP. A página de configurações exibe um aviso quando o nome do terminal está ausente ou a moeda não é suportada.
The payment went through, but the order stays Pending payment: a notificação não chegou ou foi rejeitada. Verifique se o Notifications está ativado e se o Trusted IP lista os endereços dos quais a Tranzila envia notificações. Erros são sempre gravados em WooCommerce > Status > Logs, origem wcp_tranzila_payment_gateway. A mensagem de que um IP não está na lista Trusted IP significa que é preciso corrigir a configuração do Trusted IP ou do proxy: atrás de um proxy ou CDN, o servidor web deve repassar ao PHP o IP real do visitante.
Notification answers Forbidden: veio de um endereço IP que não está no Trusted IP.
Notification answers Bad request or Not found: o pedido, a chave do pedido, o terminal ou o índice de transação na notificação não correspondem a nenhum pedido desta loja.
Notification answers Accepted for manual review: o Trusted IP está vazio, então a notificação não pôde ser verificada. Um pagamento bem-sucedido coloca o pedido em espera. Preencha o Trusted IP para confirmar pagamentos automaticamente.
Notification answers Busy, retry: o pedido estava sendo processado por outra requisição no mesmo momento, e a notificação não foi aplicada. Confira o pagamento no terminal da Tranzila; se o pedido ainda aguarda pagamento e o pagamento estiver aprovado lá, altere o status manualmente.
Some paid orders are On hold: leia a nota do pedido. O valor, a moeda ou o token do handshake não correspondiam, ou a notificação não pôde ser verificada (Trusted IP vazio ou notificações desativadas). Confira o pagamento no terminal da Tranzila e altere o status manualmente.
The payment page does not open with the handshake on: verifique o nome e a senha do terminal, se o handshake está ativado no terminal da Tranzila e se o IP do seu servidor está permitido lá. O log mostra o motivo.
Refunds fail: os reembolsos exigem a Terminal password (TranzilaPW). Alguns terminais também exigem uma senha de crédito separada; informe-a em Refund password (CreditPass). Pedidos pagos em outro terminal devem ser reembolsados nesse terminal.
Other currencies: o plugin suporta ILS, USD, EUR e GBP. Desenvolvedores podem ajustar a lista com o filtro tranzila_p_currency_map.
The license block shows an error: 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 de licença deste plugin são sempre removidos. As configurações do gateway, os dados da Tranzila armazenados nos pedidos e os logs do plugin (incluindo os arquivos de log rotacionados) são removidos somente se o 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.
A Tranzila é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Tranzila.