VibeFox TrustPay for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões mais antigas do PHP.
Conta da finby (TrustPay): você precisa de um projeto no Merchant Portal da finby, com o seu Project ID e a sua Secret key. Para pagamentos de teste, precisa de um projeto de teste (playground) separado, com seu próprio Project ID e Secret key. Nenhuma outra chave é necessária: a Secret key serve tanto para obter acesso à API quanto para verificar a assinatura das notificações de pagamento.
URL de notificação acessível: a finby precisa conseguir alcançar a sua loja pela internet. Um firewall, um login de manutenção ou a autenticação HTTP na frente da loja bloqueia as notificações de pagamento.
Chave de licença VibeFox: adquirida 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, localize VibeFox TrustPay Gateway na lista de módulos e clique em Configure.
3. Insira a sua chave de licença VibeFox no campo License key do bloco de licença no topo da página Configure e clique em Activate (veja Chave de licença).
4. Insira o Project ID e a Secret key do seu projeto de teste e, para pagamentos reais, do seu projeto de produção (veja Configuração).
5. Ative Enable / Disable e clique em Save. Faça um pagamento de teste com Test mode ativado e, em seguida, desative Test mode para receber pagamentos reais.
Na instalação, o módulo cria dois status de pedido, Awaiting TrustPay payment e TrustPay payment on hold. O PrestaShop vincula um novo módulo de pagamento aos países ativos no momento da instalação. Para os países que você adicionar depois, marque o módulo em Payment > Preferences. Ali também é possível limitar o módulo por moeda e por grupo de clientes.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox TrustPay 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 módulo está ativado, mas o Project ID ou a Secret key do modo atual está vazio, e quando a moeda padrão da loja não é suportada. Nos dois casos, o método de pagamento fica oculto na finalização de compra.
TrustPay / finby
Enable / Disable: Enable TrustPay / finby card payments ativa ou desativa o método de pagamento. Padrão: off.
Title: o nome do método de pagamento que o cliente vê na finalização de compra. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Card payment (TrustPay). Obrigatório.
Description: o texto exibido abaixo do método de pagamento na finalização de compra. Padrão: Pay securely by card on the TrustPay / finby payment page.
Credenciais da API
Copie o Project ID e a Secret key do seu projeto no Merchant Portal da finby (TrustPay). A seção tem um link para o Merchant Portal. Os pagamentos de teste usam um projeto de teste (playground) separado, com seu próprio Project ID e Secret key. Nenhum valor real é cobrado ali.
Test mode: usa o projeto de teste (sem pagamentos reais). Novos pagamentos e reembolsos usam as credenciais de teste. Os reembolsos de um pedido são sempre feitos no projeto pelo qual o pedido foi pago. Padrão: on. Enquanto estiver ativado, os clientes veem Test mode: no real payment will be taken. abaixo do método de pagamento.
Live Project ID: o Project ID numérico do seu projeto de produção.
Live Secret key: a Secret key do projeto de produção. Ela é usada para obter tokens de acesso à API e para verificar as notificações de pagamento.
Test Project ID: o Project ID numérico do seu projeto de teste (playground).
Test Secret key: a Secret key do projeto de teste.
O Project ID deve conter apenas dígitos. Se você salvar outro valor, a página mostra must contain digits only — the previous value was kept. e os demais campos são salvos. As Secret keys são salvas exatamente como digitadas; somente os espaços no início e no fim são removidos. Secret keys 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. Salvar as configurações também descarta os tokens de acesso à API em cache, para que as novas credenciais sejam usadas imediatamente.
Clear saved secrets: marque uma Secret key e clique em Save para removê-la. Um campo vazio mantém o valor salvo.
Notificações de pagamento
O pedido só é marcado como pago depois que a finby o confirma com uma notificação assinada. O módulo envia a URL de notificação com cada pagamento automaticamente, então você não precisa configurá-la. A seção mostra a URL em Notification URL. Com URLs amigáveis, ela tem a forma https://your-shop/module/wcp_trustpay_gateway/callback, possivelmente com um código de idioma. Você também pode informá-la como URL de notificação dos seus projetos no Merchant Portal. Notificações sem assinatura válida são rejeitadas.
O módulo não pede à finby o status do pagamento por conta própria. Se uma notificação não conseguir chegar à sua loja, nenhum pedido é criado até que a finby a entregue. A finby repete as notificações.
Avançado
Order status after payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido em uma única etapa, para que o cliente receba um único e-mail.
Debug logging: adiciona as requisições à API e as notificações em logs/trustpay_p_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os erros são sempre registrados, mesmo com esta opção desativada. O log não contém chaves, tokens, dados de cartão nem dados de clientes. Padrão: off.
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 do módulo e o log. Os dados dos pedidos são mantidos: pedidos, registros de pagamento da TrustPay e reembolsos, e os status de pedido. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão, Card payment (TrustPay)) e confirma o pedido. O método de pagamento só é oferecido nas moedas suportadas: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF e USD. Valores em HUF são enviados sem casas decimais.
Pagamentos com cartão precisam de um endereço. Se a rua, a cidade, o CEP ou o país estiver faltando, o cliente vê Please enter your billing address (street, city, postcode and country) — it is required for card payments.
O módulo cria na finby uma solicitação de pagamento com cartão pelo total do carrinho, na moeda do carrinho. Nome, endereço e e-mail do cliente são enviados para o 3-D Secure, e o número do carrinho é enviado como referência. Nesse ponto, o pedido ainda não existe. O cliente é redirecionado para a página de pagamento da finby e paga com o cartão ali. A página abre no idioma do carrinho, quando a finby oferece suporte a ele; caso contrário, em inglês.
Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que a finby o confirma com a notificação assinada. O retorno em si nunca altera o status do pagamento. Se a notificação já tiver chegado, o cliente vê a página padrão de confirmação do pedido. Se não, aparece a página Payment confirmation, que informa que a finby está confirmando o pagamento com cartão e que o pedido será criado assim que a confirmação chegar. Ela tem um botão Check again e um botão Back to checkout. Enquanto o pedido estiver em Awaiting TrustPay payment ou TrustPay payment on hold, a página de confirmação mostra Your card payment is being confirmed by TrustPay / finby. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Se a finby recusou o pagamento ou o pedido não pago foi cancelado, ela mostra Your card payment was not completed. Please contact us about this order.
Se o cliente cancelar na página de pagamento, ele volta à finalização de compra com The card payment was cancelled. You can try again or choose another payment method. Se a página de pagamento retornar um erro, ou se a finby já tiver recusado o pagamento, a mensagem é The card payment was not completed. Please try again or choose another payment method. O carrinho é mantido e o cliente pode pagar novamente.
Se a finby não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com We could not start the card payment. Please try again in a moment or choose another payment method. O motivo técnico é registrado no log.
A notificação funciona enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja.
O módulo aceita apenas pagamentos com cartão, como compra em uma única etapa na página da finby. Não há transferências bancárias nem outros meios de pagamento da finby, botões de Apple Pay ou Google Pay no seu site, cartões salvos, assinaturas ou pagamentos recorrentes, autorização e captura separadas nem consulta de status.
Pedidos e reembolsos
Status do pedido
No order yet: o cliente foi enviado à finby e não pagou, ou a notificação ainda não chegou. Existe apenas o carrinho.
Payment accepted or Delivered: a finby confirmou o pagamento, e o valor e a moeda coincidem com a solicitação de pagamento e com o total do carrinho. O status segue Order status after payment. O pagamento é registrado com o ID da solicitação de pagamento da finby como ID da transação, e uma nota mostra o valor, a solicitação de pagamento e o projeto (teste ou produção).
Awaiting TrustPay payment: a finby informou que o pagamento mais recente está pendente. O pedido passa para o status pago quando a finby confirma o pagamento.
TrustPay payment on hold: definido em dois casos. O pagamento foi apenas autorizado, não capturado: capture-o ou cancele-o no Merchant Portal da finby e depois atualize o pedido. Ou o valor ou a moeda pagos diferem da solicitação de pagamento ou do total do carrinho, por exemplo porque o carrinho foi alterado depois que o cliente foi enviado à página de pagamento: verifique o pagamento antes do envio. A nota explica o caso.
Payment error: a finby recusou o pagamento mais recente de um pedido que estava aguardando. A nota mostra o motivo quando a finby o envia. Um pagamento confirmado depois ainda move o pedido para o status pago.
Refunded: o pagamento foi reembolsado integralmente pelo módulo.
Pedidos cancelados ou reembolsados nunca são reabertos por um pagamento atrasado. Uma nota pede que você restaure o pedido ou reembolse o pagamento no Merchant Portal. Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado e uma nota pede que você reembolse a duplicidade no Merchant Portal. Chargebacks e disputas informados pela finby são adicionados como notas.
Bloco de pagamento TrustPay / finby
A página do pedido mostra um bloco TrustPay / finby payment com o ID da solicitação de pagamento, o ID do pagamento na finby, o projeto, o status do pagamento, os valores solicitado e pago, o valor reembolsado, um selo Test project para pagamentos de teste, o histórico de reembolsos e as TrustPay notes do pedido.
Reembolsos
No bloco TrustPay / finby payment, digite o valor (o valor ainda não reembolsado é preenchido automaticamente), opcionalmente um motivo, e clique em Refund via TrustPay. Confirme a pergunta Refund this amount through TrustPay? This cannot be undone. Reembolsos totais e parciais são suportados. Você precisa ter o direito de editar pedidos; o acesso às páginas de Módulos não é necessário. Os reembolsos são feitos no valor e na moeda que a finby informou para o pagamento. Assim, após uma divergência de valor, você pode reembolsar até o que o cliente de fato pagou, e não o total do pedido. Reembolsos em HUF devem ser valores inteiros.
O reembolso vai para o projeto pelo qual o pedido foi pago (teste ou produção), mesmo que você tenha trocado de modo depois. Esse projeto precisa ter o Project ID e a Secret key configurados, e o seu Project ID não pode ter mudado. Um reembolso só é registrado quando a finby o aceita. Caso contrário, o bloco mostra TrustPay refused the refund: com o motivo, e nenhum reembolso é registrado. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas. Um reembolso total coloca o pedido em 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 pela finby. Reembolsos feitos no Merchant Portal da finby não são registrados como reembolsos. Se a finby enviar uma notificação sobre eles, ela é adicionada como nota e o status do pedido não muda.
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 TrustPay Gateway é o primeiro bloco em Modules > Module Manager > VibeFox TrustPay Gateway > Configure, acima das configurações. Insira 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-trustpay e o link Manage licenses and domains in your account, que abre a sua conta em vibefox.net. Apenas 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. Libere-a na sua conta em vibefox.net.
Sem uma chave ativa, o pagamento com cartão 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 pode 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 TrustPay e pelo retorno à loja, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de 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 inserida e, depois, uma vez por semana. Não é necessário nenhum cron job. Desinstalar ou redefinir o módulo sempre remove a chave de licença e o status da licença.
Solução de problemas
Card payment (TrustPay) 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 o seu Project ID e a sua Secret key: Test Project ID e Test Secret key no modo de teste, Live Project ID e Live Secret key no modo de produção. A moeda do carrinho deve ser uma das moedas suportadas. A página de configurações mostra um aviso quando as credenciais estão faltando ou a moeda padrão não é suportada. 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 à sua loja. Verifique se a URL exibida em Notification URL está acessível pela internet (sem firewall, login de manutenção ou autenticação HTTP). A finby repete a notificação, e o pedido é criado quando ela chega. Ative Debug logging e consulte o campo Log na página do módulo.
O log mostra Notification rejected: invalid signature or unknown project: a notificação veio de um projeto cujo Project ID não está nas configurações, ou a Secret key desse projeto está errada. A loja responde Invalid signature e nada é alterado. Verifique o Project ID e a Secret key do modo em que o pagamento foi feito.
O log mostra Notification ignored: a notificação se refere a uma solicitação de pagamento que esta loja não criou para aquele carrinho, ou a outro projeto ou modo diferente daquele com o qual o pagamento foi iniciado. Nada é alterado.
A notificação recebe a resposta Busy, retry later ou Temporary error: o carrinho estava sendo atualizado por outra notificação naquele mesmo momento, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A finby tenta novamente. O log mostra o motivo.
O cliente vê We could not start the card payment: abra o log. Um Project ID ou uma Secret key incorretos geram uma mensagem informando que a finby recusou as credenciais do projeto. Verifique se as credenciais de teste estão nos campos de teste e as de produção nos campos de produção.
Card payment is temporarily unavailable: o cliente vê isso quando o modo atual não tem Project ID nem Secret key. Preencha-os e salve.
O pedido está em TrustPay payment on hold: leia as notas no bloco TrustPay / finby payment (veja Status do pedido). Verifique o pagamento no Merchant Portal antes do envio e depois atenda o pedido ou reembolse o pagamento.
O reembolso falha com uma mensagem sobre o projeto: o pedido foi pago pelo projeto de teste ou de produção, e o Project ID ou a Secret key desse modo não estão configurados, ou agora há outro Project ID salvo ali. Insira as credenciais desse projeto ou reembolse o pagamento no Merchant Portal da finby.
Invalid refund amount: at most … can be refunded: o valor é maior que o valor pago menos os reembolsos já feitos pelo módulo.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox TrustPay Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Os tokens de acesso à API em cache são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações do módulo e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. Os registros de pagamento da TrustPay e os reembolsos, e os status de pedido Awaiting TrustPay payment e TrustPay payment on hold, são sempre mantidos, para que pedidos pagos antes possam ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.
TrustPay e finby são marcas registradas de seus respectivos titulares. Este módulo não é afiliado nem endossado pela TrustPay ou pela finby.