VibeFox Tranzila for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.
Moeda da loja: ILS, USD, EUR ou GBP. Para outras moedas do carrinho, a forma de pagamento fica oculta 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 pela página do pedido. 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 a sua loja 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 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, depois, encontre VibeFox Tranzila Payment Gateway na lista de módulos e clique em Configure.
3. Informe 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. Informe o Terminal name (supplier) e a Terminal password (TranzilaPW), se você usar o handshake ou os reembolsos.
5. 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.
6. Recomendado: ative o handshake no terminal da Tranzila, permita ali o IP do seu servidor e depois ative o Handshake no módulo.
7. Ative o Enable/Disable, clique em Save e faça um pagamento de teste com o terminal de teste da Tranzila.
Ao instalar, o módulo cria o status de pedido Tranzila payment on hold. O PrestaShop oferece a um novo módulo de pagamento todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Tranzila Payment 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 nome do terminal está vazio (a forma de pagamento fica oculta na finalização de compra), quando as notificações estão desativadas ou o Trusted IP está vazio (os pedidos pagos ficam 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 padrão da loja não é compatível. Ao salvar, um nome de terminal inválido, uma entrada inválida no Trusted IP ou um campo numérico que não seja um número inteiro não são salvos: a página mostra um erro e o valor anterior é mantido. Um número fora da faixa permitida é salvo como o valor permitido mais próximo, e a página informa isso.
Tranzila
Enable/Disable: Enable Tranzila Payment Gateway ativa ou desativa a forma de pagamento. Padrão: desativado.
Title: o nome da forma de pagamento que o cliente vê na finalização de compra e o título da página de pagamento. É também o nome da forma de pagamento gravado no pedido. Padrão: Credit Card (Tranzila).
Description: o texto exibido abaixo da forma 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, dígitos, «-» e «_». Enquanto não for informado, a forma 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 pela página do pedido.
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.
As senhas salvas nunca são exibidas novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas se quiser alterá-lo.
Clear saved passwords: marque uma senha e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Página de pagamento
Payment page version: a página da Tranzila exibida no iframe.
Payment page language: o idioma da página da Tranzila: Site language, hebraico, inglês, russo, espanhol, alemão, francês ou japonês. Padrão: hebraico. Site language usa o idioma do carrinho do cliente quando ele é um desses idiomas; caso contrário, inglês.
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: trava o valor com um token de handshake (recomendado). Antes de abrir a página de pagamento, a loja pede à Tranzila um token único vinculado ao valor, 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 ali. Padrão: desativado.
Confirmação do pagamento
As notificações da Tranzila não são assinadas. Um pedido só é criado como pago quando a notificação vem de um Trusted IP e o seu token da página de pagamento, carrinho, terminal, valor e moeda correspondem à página de pagamento. Com o handshake, o token também precisa corresponder à página de pagamento. O retorno do cliente da página de pagamento nunca marca um pedido como pago.
Notifications: confirma os pagamentos automaticamente com as notificações da Tranzila (notify URL). Padrão: ativado. Quando as notificações estão desativadas, um cliente que volta de uma página de pagamento bem-sucedida cria o pedido no status Tranzila payment on hold, e você confirma o pagamento manualmente depois de conferir o terminal da Tranzila.
Notification URL: exibida apenas para informação. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_tranzila_payment_gateway/notify, possivelmente com um código de idioma. A URL é enviada à Tranzila em cada pagamento, por isso você não precisa informá-la no terminal da Tranzila.
Trusted IP: os endereços IP ou faixas CIDR dos servidores da Tranzila que enviam as 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 cria o pedido no status Tranzila payment on hold para revisão manual, e uma recusa informada não altera nada.
Avançado
Debug log: registra os eventos da página de pagamento, das notificações e dos reembolsos em logs/tranzila_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Avisos e erros são sempre registrados, mesmo quando esta opção está desativada. Senhas, tokens e dados de clientes nunca são gravados. Padrão: desativado.
Log: mostra o tamanho e as últimas entradas do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações e os logs. As transações e os reembolsos da Tranzila e o status de pedido Tranzila payment on hold sempre permanecem, porque os pedidos antigos precisam deles. Padrão: desativado.
Finalização de compra
Na etapa de pagamento, o cliente escolhe a forma de pagamento (por padrão Credit Card (Tranzila)) e vê a descrição e a observação After you confirm, you will enter your card details on the secure Tranzila payment page. The order is created once Tranzila confirms the payment. Depois de confirmar, o cliente vai para uma página de pagamento da sua loja. Ali abre-se a página de pagamento da Tranzila em um iframe, com o total do carrinho na moeda do carrinho, os dados de cobrança 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. Neste ponto, ainda não existe pedido.
Depois de um pagamento bem-sucedido, a Tranzila devolve o cliente e toda a janela avança. O pedido só é marcado como pago depois que a Tranzila confirma o pagamento por meio de uma notificação. Se a notificação já tiver chegado, o cliente vê a página padrão de confirmação do pedido com Your payment with Tranzila has been received. 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 a notificação ainda não tiver chegado, uma página Payment confirmation 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. e um botão Check again.
Se o pagamento for recusado ou cancelado, o cliente volta à finalização de compra 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 carrinho é mantido e nenhum pedido é criado. Cada vez que a página de pagamento é aberta, é uma nova página de pagamento com seu próprio token.
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 botão Choose another payment method. O motivo técnico é gravado no log.
A notificação funciona com a loja em modo de manutenção e não é bloqueada pela restrição de países da sua loja. A mesma página de pagamento é usada com os temas Classic e Hummingbird.
O módulo 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
Status do pedido
No order yet: o cliente foi enviado à página de pagamento e não pagou, o pagamento foi recusado ou a notificação da Tranzila ainda não chegou. Existe apenas o carrinho.
Payment accepted: o pagamento foi confirmado por uma notificação verificada. O pagamento é registrado com o índice de transação da Tranzila como ID da transação, e uma nota mostra o valor, a transação, o número de autorização e o número de parcelas, quando houver.
Tranzila payment on hold: o pagamento foi informado, mas não foi aceito automaticamente: o valor, a moeda ou o token de handshake não correspondiam, 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 explica o motivo. Confira o pagamento no terminal da Tranzila e altere o status manualmente.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Se chegar um pagamento para um pedido que foi cancelado, o pedido volta ao status Payment accepted com uma nota pedindo que você confira o estoque antes do envio. Se chegar um segundo pagamento para um pedido já pago ou reembolsado, o pedido não é alterado. Uma nota pede que você o confira e reembolse o duplicado no terminal da Tranzila. Notificações repetidas da mesma transação são ignoradas.
Bloco de pagamento da Tranzila
A página do pedido mostra um bloco Tranzila payment com o índice de transação, o número de autorização, o terminal, o status, o valor pago e reembolsado, o número de parcelas, o histórico de reembolsos, todas as Payment pages of the cart com o respectivo resultado e as Tranzila notes do pedido.
Reembolsos
No bloco Tranzila payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Tranzila. Confirme a pergunta Refund this amount via Tranzila? This cannot be undone. São aceitos reembolsos totais e parciais. Você precisa ter permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. O reembolso é feito como uma transação de crédito da Tranzila do pagamento original, no terminal que o recebeu, pelo valor e na moeda que a Tranzila de fato cobrou. Assim, após uma divergência de valor ou moeda, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido.
O formulário fica disponível quando a senha do terminal está definida e o pedido tem uma transação da Tranzila confirmada com número de autorização. Caso contrário, o bloco informa o motivo, por exemplo Refunds need the terminal password (TranzilaPW) in the gateway settings. Um pedido pago em outro terminal que não o atual das configurações (por exemplo, um terminal de teste) não pode ser reembolsado pela página do pedido; reembolse-o nesse terminal da Tranzila.
Se a Tranzila não aceitar o reembolso, o bloco mostra o erro, por exemplo Tranzila declined the refund com o código e o seu significado, e nenhum reembolso é registrado. Um reembolso bem-sucedido é acrescentado ao histórico de reembolsos e às notas, com a transação de crédito da Tranzila. Um reembolso total coloca o pedido no status Refunded. Um reembolso parcial não altera o status.
O módulo não cria notas de crédito (credit slips). Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem o dinheiro pela Tranzila. Os reembolsos feitos no terminal da Tranzila não são informados à loja. 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 Tranzila Payment Gateway é o primeiro bloco em Modules > Module Manager > VibeFox Tranzila Payment 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-tranzila e o link Manage licenses and domains in your account, que abre a sua conta na vibefox.net. Somente funcionários com a permissão Configure do 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 do domínio. Libere a vaga na sua conta 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. A vitrine do PrestaShop não sabe que você está conectado ao back office, então a forma de pagamento também fica oculta para você: é possível 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: os pagamentos já iniciados continuam sendo confirmados pela notificação da Tranzila e pelo retorno à loja, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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, 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
A Tranzila não aparece na finalização de compra: verifique se a licença está ativa, se o Enable/Disable está ativado, se o Terminal name (supplier) está preenchido e se a moeda do carrinho é ILS, USD, EUR ou GBP. A página de configurações mostra um aviso quando o nome do terminal está ausente ou a moeda padrão não é compatível. 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.
O pagamento foi aprovado, mas nenhum pedido foi criado: 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 as notificações. Os erros são sempre gravados no log; veja o campo Log na página do módulo. A mensagem de que um IP não está na lista Trusted IP significa que a configuração Trusted IP ou a configuração do seu proxy precisa ser corrigida: atrás de um proxy ou CDN, o servidor web deve repassar ao PHP o IP real do visitante. Desenvolvedores cuja loja fica atrás de um reverse proxy confiável podem definir o IP com o hook actionTranzilaPRemoteIp.
A notificação responde Forbidden: ela veio de um endereço IP que não está no Trusted IP.
A notificação responde Bad request ou Not found: o carrinho, o token da página de pagamento, o terminal ou o índice de transação na notificação não correspondem a nenhuma página de pagamento desta loja.
A notificação responde Accepted for manual review: o Trusted IP está vazio, então a notificação não pôde ser verificada. Um pagamento bem-sucedido cria o pedido em espera. Preencha o Trusted IP para confirmar os pagamentos automaticamente.
A notificação responde Busy, retry: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). O log mostra o motivo. Confira o pagamento no terminal da Tranzila; se ele estiver aprovado ali e nenhum pedido tiver sido criado, entre em contato com o cliente ou crie o pedido manualmente.
Alguns pedidos estão em Tranzila payment on hold: leia as notas no bloco Tranzila payment. O valor, a moeda ou o token de 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.
A página de pagamento não abre com o handshake ativado: verifique o nome do terminal e a senha do terminal, se o handshake está ativado no terminal da Tranzila e se o IP do seu servidor está permitido ali. O log mostra o motivo.
Os reembolsos falham: 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. Se a resposta da Tranzila for inesperada, o bloco informa que o reembolso não foi confirmado: confira o terminal da Tranzila antes de tentar de novo.
Outras moedas: o módulo aceita apenas ILS, USD, EUR e GBP.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Tranzila Payment Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se o Delete data on uninstall estiver ativado, as configurações e os logs são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As transações e os reembolsos da Tranzila e o status de pedido Tranzila payment on hold são sempre mantidos, assim os 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.
A Tranzila é marca registrada do respectivo titular. Este módulo não é afiliado nem endossado pela Tranzila.