VibeFox TrustPay for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.
PHP: 8.0 ou superior.
Conta da finby (TrustPay): você precisa de um projeto no finby Merchant Portal, com o seu Project ID e a sua Secret key. Para pagamentos de teste, é necessário um projeto de teste (playground) separado, com o próprio Project ID e a própria Secret key. Não são necessárias outras chaves: a Secret key é usada 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 acessar o seu site pela internet. Um firewall, o modo de manutenção ou a proteção por senha do site bloqueia as notificações de pagamento.
Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um domínio.
Instalação
1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_trustpay_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > TrustPay / finby, ou clique em Settings abaixo do nome do plugin na página Plugins.
4. Insira a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Insira o Project ID e a Secret key do seu projeto de produção e, para testes, os do seu projeto de teste (veja Configuração).
6. Ative Enable / Disable e salve. Faça um pagamento de teste com Test mode ativado e depois desmarque Test mode para receber pagamentos reais.
Ao atualizar a partir da versão 1.0, o seu Project ID e a sua Secret key são mantidos como credenciais de produção e o modo de teste é desativado. Revise as configurações após a atualização.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > TrustPay / finby. Acima dos campos, a página avisa quando o gateway está ativado, mas o Project ID ou a Secret key do modo atual está vazio, e quando a moeda da loja não é suportada. Nos dois casos, o método de pagamento fica oculto no checkout. Na lista de métodos de pagamento, o gateway aparece como pendente de configuração até que o modo atual tenha o seu Project ID e a sua Secret key.
General
Enable / Disable: Enable TrustPay / finby card payments ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o nome do método de pagamento que o cliente vê no checkout. Padrão: Card payment (TrustPay).
Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely by card on the TrustPay / finby payment page.
API credentials
Copie o Project ID e a Secret key do seu projeto no finby (TrustPay) Merchant Portal. A seção tem um link para o Merchant Portal. Os pagamentos de teste usam um projeto de teste (playground) separado, com o próprio Project ID e a própria Secret key. Nenhum dinheiro real é cobrado ali.
Test mode: Use the test project (no real payments). 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: ativado.
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.
Um Project ID deve conter apenas dígitos. Se você salvar outro valor, a página mostra um erro e o valor anterior é mantido. As Secret keys são salvas exatamente como digitadas; apenas os espaços no início e no fim são removidos.
Payment notifications
O pedido só é marcado como pago depois que a finby confirma o pagamento com uma notificação assinada. O plugin envia automaticamente a URL de notificação com cada pagamento, então você não precisa configurá-la. A seção mostra a URL, por exemplo https://your-site/wc-api/trustpay_payment_callback/. 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 plugin não consulta o status do pagamento na finby por conta própria. Se uma notificação não conseguir chegar ao seu site, o pedido permanece em Pending payment até que a finby a entregue.
Advanced
Order status after payment: o status do pedido definido após um pagamento bem-sucedido. O status é definido em uma única etapa, assim o cliente recebe um único e-mail.
Debug logging: Log API requests and notifications adiciona detalhes ao log. Os erros são sempre registrados, mesmo quando esta opção está desativada. Os logs ficam em WooCommerce > Status > Logs, origem wcp_trustpay_gateway, e não contêm chaves, tokens, dados de cartão nem dados de clientes. Padrão: desativado.
Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (order data is kept). Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão, Card payment (TrustPay)) e faz o pedido. No modo de teste, a finalização de compra mostra Test mode: no real payment will be taken. abaixo da descrição.
Pagamentos com cartão exigem o endereço de cobrança. 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 plugin cria uma solicitação de pagamento com cartão na finby pelo total do pedido, na moeda do pedido. O nome, o endereço e o e-mail do cliente são enviados para o 3-D Secure, e o ID do pedido é enviado como referência. O cliente é redirecionado para a página de pagamento da finby e paga com o cartão ali. A página abre no idioma da sua loja, quando a finby oferece suporte a ele; caso contrário, em inglês. Uma nota no pedido mostra a solicitação de pagamento, o valor e o projeto (teste ou produção).
Depois de pagar, o cliente volta para a página de pedido recebido da sua loja, e o carrinho é esvaziado. O pedido só é marcado como pago quando a finby confirma com a notificação assinada. O retorno em si nunca altera o status do pagamento.
Se o cliente cancelar na página de pagamento, ou se a página de pagamento devolver um erro, o cliente volta para a página Pay for order com a mensagem The card payment was cancelled. You can try again or choose another payment method. ou The card payment was not completed. Please try again or choose another payment method. Uma nota é adicionada ao pedido. O cliente pode pagar novamente a partir dessa página.
Se a finby não conseguir iniciar o pagamento, o cliente vê 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.
Moedas: EUR, CZK, HUF, GBP, PLN, NOK, SEK, DKK, BGN, RON, CHF e USD. Valores em HUF são enviados sem casas decimais. Na página Pay for order, a moeda do pedido é verificada.
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 vem com traduções para inglês, eslovaco e tcheco.
O plugin 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 métodos de pagamento da finby, nem botões de Apple Pay ou Google Pay, nem cartões salvos, nem assinaturas ou pagamentos recorrentes, nem autorização e captura separadas, nem consulta de status.
Pedidos e reembolsos
Status do pedido
Pending payment: o cliente foi enviado à finby e ainda não pagou, ou a notificação ainda não chegou.
Processing or Completed: a finby confirmou o pagamento, e o valor e a moeda conferem com a solicitação de pagamento e com o total do pedido. O status segue Order status after payment. A nota do pedido mostra o valor, a solicitação de pagamento e o projeto. O ID da transação é o ID da solicitação de pagamento na finby.
On hold: definido em três casos. O pagamento ainda está pendente na finby, e o pedido aguarda o resultado final. O pagamento foi apenas autorizado, não capturado: capture-o ou anule-o no finby Merchant Portal e depois atualize o pedido. Ou o valor ou a moeda pagos diferem da solicitação de pagamento ou do total do pedido, por exemplo porque o pedido foi editado depois que o cliente foi enviado à página de pagamento: verifique o pagamento antes do envio. A nota do pedido explica o caso.
Failed: a finby recusou o último pagamento do pedido. A nota mostra o motivo quando a finby o envia. O cliente pode pagar novamente em Pay for order.
Pedidos cancelados ou reembolsados nunca são reabertos por um pagamento atrasado. Uma nota pede que você restabeleça o pedido ou reembolse o pagamento no Merchant Portal. Se um segundo pagamento chegar para um pedido que já está pago, o pedido não é alterado e uma nota pede que você reembolse a duplicata no Merchant Portal. Chargebacks e contestações informados pela finby são adicionados como notas.
Reembolsos
Abra o pedido, clique em Refund, informe o valor e clique em Refund via Card payment (TrustPay) (o botão mostra o seu Title). Reembolsos totais e parciais são suportados. O reembolso vai para o projeto pelo qual o pedido foi pago (teste ou produção), mesmo que você tenha trocado de modo desde então, por isso o Project ID e a Secret key desse modo precisam estar configurados. Reembolsos em HUF devem ser valores inteiros.
Um reembolso só é registrado quando a finby o aceita. Caso contrário, o WooCommerce mostra TrustPay refused the refund: com o motivo, e nenhum reembolso é criado. Um reembolso bem-sucedido é adicionado às notas do pedido.
Reembolsos feitos no finby Merchant Portal não são registrados como reembolsos do WooCommerce. Se a finby enviar uma notificação sobre eles, ela é adicionada como nota do pedido, e o status do pedido não muda.
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 > TrustPay / finby. 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 na 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 da vibefox.net.
Sem uma chave ativa, o método de pagamento não é exibido aos clientes no checkout. 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 de forma automática em segundo plano.
Solução de problemas
Card payment (TrustPay) não aparece no checkout: verifique se a licença está ativa, se Enable / Disable está ativado e se o modo atual tem o Project ID e a 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 da loja, ou a moeda do pedido na página Pay for order, deve ser uma das moedas suportadas. A página de configurações mostra um aviso nos dois casos. Desenvolvedores podem alterar a lista de moedas com o filtro trustpay_p_supported_currencies.
O pagamento foi feito, mas o pedido continua em Pending payment: a notificação não chegou à sua loja. Verifique se https://your-site/wc-api/trustpay_payment_callback/ está acessível pela internet (sem firewall, modo de manutenção ou proteção por senha). A finby repete a notificação. Veja WooCommerce > Status > Logs, origem wcp_trustpay_gateway.
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 o pedido não é 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 pertence a uma solicitação de pagamento que esta loja não criou para o pedido, ou a um projeto diferente daquele com o qual o pagamento foi iniciado. O pedido não é alterado.
A notificação recebe a resposta Busy, retry later: o pedido estava sendo atualizado por outra notificação no mesmo momento. A finby a repete.
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.
O pagamento com cartão está temporariamente indisponível: o cliente vê essa mensagem quando o modo atual não tem Project ID nem Secret key. Preencha-os e salve.
O pedido está On hold com uma nota de divergência de valor ou moeda: a notificação era autêntica, mas o valor ou a moeda pagos diferem da solicitação de pagamento ou do total 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 preenchidos, ou outro Project ID está salvo agora. Informe as credenciais desse projeto ou reembolse o pagamento no finby Merchant Portal.
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 da 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, bem como os tokens de acesso à API em cache, são sempre removidos. As configurações do gateway e os logs do plugin (arquivos de log, inclusive arquivos antigos rotacionados, e entradas de log no banco de dados) são removidos somente se Delete data on uninstall estava ativado. Caso contrário, são mantidos para uma reinstalação posterior. Os dados dos pedidos são mantidos: os pedidos existentes preservam suas notas de pagamento, IDs de solicitação de pagamento e IDs de transação.
TrustPay e finby são marcas comerciais de seus respectivos proprietários. Este plugin não é afiliado nem endossado pela TrustPay ou pela finby.