VibeFox Tpay 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 anteriores do PHP. 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 sua Open API não tem campo de moeda, por isso o método de pagamento fica oculto quando o carrinho usa outra moeda.

Acesso à internet para a sua loja: 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 (sem bloqueio por firewall ou autenticação HTTP).

Conta no Tpay: você precisa destes valores do painel de comerciante do 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 do Tpay.

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 depois o VibeFox Tpay Payment na lista de módulos e clique em Configure.

3. Digite 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. Digite as chaves Sandbox e as chaves Production (veja Configuração). No painel do Tpay não é preciso configurar nada além do código de segurança: o endereço de notificação é enviado em cada transação.

5. Ative Enable/Disable e clique em Save. Teste um pagamento no modo sandbox e depois desative Sandbox mode para aceitar pagamentos reais.

Na instalação, o módulo cria o status de pedido Tpay payment on hold. O PrestaShop oferece um novo módulo de pagamento para todas as moedas, países e grupos de clientes. Você pode limitá-los em Payment > Preferences; o PLN precisa continuar permitido para o módulo.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Tpay Payment > 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 Sandbox mode is on: payments go to the Tpay sandbox and no real money is charged. enquanto o modo sandbox estiver ativo. 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 padrão da loja não é PLN e quando a extensão OpenSSL do PHP está ausente com a verificação JWS ativa (os pagamentos não seriam confirmados). Espaços colados junto com o Merchant ID ou o Client ID são removidos ao salvar.

Tpay

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. Também é o nome do método de pagamento salvo no pedido. Padrão: Tpay. Obrigatório.

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: usa o sandbox do Tpay (pagamentos de teste, sem dinheiro real) com as chaves Sandbox e openapi.sandbox.tpay.com. Desative para aceitar pagamentos reais com as chaves Production. Os reembolsos sempre vão para o ambiente em que o pedido foi pago. Padrão: ativado.

Production keys

Onde encontrá-las: no painel de comerciante do 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 (números). 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.

Sandbox keys

O sandbox é uma conta de teste separada do Tpay, com chaves próprias (veja a documentação da API do Tpay). Elas são usadas somente enquanto Sandbox mode estiver ativo.

Sandbox Merchant ID: o Merchant ID da conta sandbox.

Sandbox Client ID: o Open API Client ID da conta sandbox.

Sandbox Client secret: o Open API Client secret da conta sandbox.

Sandbox Security code: o código de segurança das notificações da conta sandbox.

Os segredos salvos (Client secret e Security code dos dois ambientes) nunca são exibidos novamente. O campo fica vazio e mostra Saved - leave empty to keep it. Digite um valor novo apenas se quiser alterá-lo.

Clear saved secrets: marque um segredo e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Payment notifications

Notification URL: o Tpay confirma os pagamentos no endereço mostrado aqui. Com URLs amigáveis, ele tem este formato: https://your-shop/module/wcp_tpay_payment/notify, possivelmente com um código de idioma como /en/. O endereço é enviado automaticamente em cada transação; nada precisa ser configurado no painel do Tpay além do código de segurança. Um pedido só é criado depois de uma notificação com soma de verificação e assinatura válidas e valor correspondente (ou de uma verificação de status correspondente quando o cliente retorna). O Tpay repete uma notificação até que a sua loja a aceite.

JWS signature: também verifica a X-JWS-Signature das notificações com o certificado do Tpay (recomendado). Requer a extensão OpenSSL do PHP e conexões HTTPS de saída para secure.tpay.com. Os certificados ficam em cache por um dia. A soma de verificação MD5 é sempre verificada. Padrão: ativado.

Advanced

Debug log: registra os eventos de pagamento: somente eventos técnicos (sem chaves e sem dados do cliente) no arquivo logs/wc_tp_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Padrão: desativado. Enquanto estiver desativado, nada é gravado, nem mesmo os erros; por isso, ative antes de procurar a causa de um problema.

Log: mostra o tamanho e as entradas mais recentes do registro. Clique em Clear log para esvaziá-lo.

Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações do módulo e o registro. Os pedidos e os seus dados de pagamento do Tpay são sempre mantidos. Padrão: desativado.

Finalização de compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Tpay). No modo sandbox, a opção de pagamento mostra Sandbox mode - no real money is charged. Após a confirmação, o módulo cria uma transação do Tpay pelo total do carrinho em PLN, com a descrição Cart # e o número do carrinho, envia o nome, o e-mail, o endereço de cobrança 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 da loja (outros idiomas recebem inglês). Ali o cliente escolhe BLIK, uma transferência bancária, um cartão ou outro método habilitado na sua conta do Tpay, e paga. Nesse ponto ainda não existe pedido.

O pedido só é marcado como pago depois que o Tpay confirma. O Tpay envia uma notificação para a sua loja; o módulo verifica a soma de verificação MD5 com o código de segurança, o Merchant ID e (quando ativada) a assinatura JWS, usando as chaves do ambiente em que o pagamento foi iniciado, e depois o valor: ele precisa ser igual ao valor solicitado para esta tentativa de pagamento e ao total do carrinho, e o valor pago não pode ser menor. Notificações sem soma de verificação ou assinatura válidas são rejeitadas. Em seguida o pedido é criado e o cliente recebe a página padrão de confirmação do pedido.

Depois de pagar, o cliente volta para a sua loja. Apenas retornar não marca nada como pago. Se a notificação ainda não tiver chegado, o módulo 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, uma página de Payment confirmation 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 botão Refresh e um botão Pay again que leva de volta à finalização de compra. A notificação cria o pedido assim que chega.

Se o Tpay informar que o pagamento não foi concluído, o cliente volta à finalização de compra com a mensagem Tpay reports that the payment did not go through. Please try again or choose another payment method. Se o pagamento falhar na página do Tpay, o Tpay envia o cliente de volta à página de finalização de compra. O carrinho é mantido nos dois casos. Se o pedido foi para espera, a página de confirmação mostra Your payment is being verified. We will contact you as soon as it is confirmed.

Cada tentativa de pagamento tem sua própria referência. Quando o cliente paga novamente, as transações não pagas anteriores do carrinho são canceladas no Tpay; um pagamento que já foi feito por um link anterior continua sendo aceito. Se o carrinho já tiver um pedido, o cliente vai para a página de confirmação desse pedido em vez de iniciar um novo pagamento.

Se o Tpay não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com a mensagem The Tpay payment could not be started. Please try again or choose another payment method. e o motivo é registrado no log (quando o Debug log está ativado).

O endereço de notificação funciona mesmo quando a loja está em modo de manutenção e não é bloqueado pela restrição de países da sua loja.

O módulo funciona somente em PLN. Não há seleção de banco ou de código BLIK na loja (o cliente escolhe na página do Tpay), nem cartões salvos, nem assinaturas, nem botões de Apple Pay ou Google Pay na loja, nem simuladores de parcelamento.

Pedidos e reembolsos

Status do pedido

No order yet: o cliente foi enviado ao Tpay e não pagou, ou o Tpay ainda não confirmou o pagamento. Existe apenas o carrinho. Um pagamento malsucedido também não cria pedido.

Payment accepted: o Tpay confirmou o pagamento. O pagamento é registrado com o título da transação do Tpay (TR-...) como ID da transação. Uma nota informa se ele foi confirmado pela notificação ou pela verificação de status, o ambiente e qualquer pagamento excedente.

Tpay payment on hold: chegou um pagamento, mas o valor era diferente do valor solicitado ou do total do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento começou), apenas parte foi paga, ou o pagamento chegou depois que o pedido foi cancelado. A nota explica o motivo. Verifique o pagamento no painel do Tpay e depois atenda ou reembolse o pedido. Se o cliente pagar o valor correto em uma nova tentativa, o pedido passa para Payment accepted.

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

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. Um chargeback informado pelo Tpay acrescenta uma nota.

Bloco de pagamento do Tpay

A página do pedido mostra um bloco Tpay payment com o título e o ID da transação do Tpay, a referência do pagamento (CRC), o ambiente (com a etiqueta Sandbox para pagamentos de sandbox), o status do pagamento e como ele foi confirmado, o valor pago, o total do pedido e o valor reembolsado, o histórico de reembolsos, todas as Payment attempts do carrinho e as Payment notes do pedido.

Reembolsos

No bloco Tpay payment, digite o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo, e clique em Refund via Tpay. Confirme a pergunta Refund this amount through Tpay? This cannot be undone. Reembolsos totais e parciais são suportados em pedidos com pagamento recebido pelo Tpay, inclusive pedidos em espera. Você precisa do direito de editar pedidos; o acesso às páginas Modules não é necessário. Você pode reembolsar até o valor que a transação do Tpay que pagou recebeu, no máximo o total do pedido: após um pagamento parcial ou um carrinho alterado, o bloco mostra Refundable (paid through Tpay). 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ó é considerado feito quando o Tpay o confirma; um reembolso recusado ou não confirmado pelo Tpay aparece como erro e não é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, junto com o motivo que você digitou (o motivo não é enviado ao Tpay). Reembolsar todo o valor reembolsável muda o pedido para Refunded. Um reembolso parcial não altera o status.

O módulo não cria notas de crédito. Os botões padrão de reembolso do PrestaShop na página do pedido não devolvem dinheiro pelo Tpay. Reembolsos feitos no painel de comerciante do Tpay não são adicionados ao PrestaShop automaticamente.

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 Tpay Payment é o primeiro bloco em Modules > Module Manager > VibeFox Tpay Payment > 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-tpay 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 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. 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 os reembolsos 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 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 digitadas (Merchant ID, Client ID, Client secret, Security code). Verifique se a moeda do carrinho é PLN e se o módulo está permitido para PLN, para o país do cliente e para o grupo do cliente em Payment > Preferences. A página de configurações mostra um aviso para chaves ausentes e para uma moeda da loja diferente de PLN.

O pagamento foi feito, mas nenhum pedido foi criado: o Tpay não conseguiu entregar a notificação ou ela foi rejeitada. Ative o Debug log e veja o campo Log na página do módulo. As causas mais comuns são um código de segurança ou um Merchant ID errados para o ambiente do pagamento, um endereço de notificação bloqueado (firewall, autenticação HTTP) ou um servidor sem OpenSSL ou sem HTTPS de saída para a verificação JWS. O pedido também é criado quando o cliente volta à loja depois de pagar.

Notification answered FALSE - invalid checksum: o Merchant ID ou o código de segurança nas configurações não correspondem à 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 não está instalado 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.

Notification answered FALSE - busy, retry later or FALSE - order could not be created: o carrinho estava sendo processado por outra requisição no mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). O Tpay repete a notificação automaticamente. Ative o Debug log para ver o motivo.

A URL de notificação mostra FALSE - POST only in the browser: isso é normal. A URL aceita apenas notificações do Tpay.

O pedido está em Tpay payment on hold: leia as notas no bloco Tpay payment (veja Status do pedido), verifique o pagamento no painel do Tpay e depois atenda o pedido ou reembolse o pagamento.

O cliente viu The Tpay payment could not be started: as chaves do modo atual estão erradas ou o Tpay recusou a requisição. Ative o Debug log; o log mostra o erro do Tpay.

O cliente viu We could not match this payment to an order: o link de retorno não pertencia ao carrinho do cliente. Se o cliente foi cobrado, a notificação ainda cria o pedido; verifique o painel do Tpay.

O reembolso falha: se a mensagem disser que as chaves estão ausentes, digite as chaves do ambiente em que o pedido foi pago. Se a mensagem disser que o valor é alto demais, só é possível reembolsar no máximo o valor exibido. Se o Tpay não confirmou o reembolso, verifique a transação no painel de comerciante do Tpay antes de tentar de novo.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Tpay Payment e escolha Uninstall. A chave de licença e o status de licença deste módulo são sempre removidos. Os tokens de acesso do Tpay e os certificados em cache são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações do módulo e o registro também são removidos. Se estiver desativado, as configurações são mantidas para uma reinstalação futura. As transações e reembolsos do Tpay e o status de pedido Tpay payment on hold são sempre mantidos, para que pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

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