VibeFox Paytrail for WooCommerce — Ajuda
Requisitos
WordPress: 6.0 ou superior.
WooCommerce: 7.0 ou superior, instalado e ativo. O plugin não será ativado sem ele.
PHP: 8.0 ou superior.
Moeda da loja: EUR. A Paytrail aceita exclusivamente euros. Para qualquer outra moeda, o método de pagamento fica oculto na finalização de compra. Os valores são enviados em centavos.
Acesso à internet para o seu site: a Paytrail confirma cada pagamento com um callback de servidor para servidor, portanto o site deve estar acessível pela internet. Mesmo sem callbacks, os pedidos ainda são confirmados quando o cliente retorna da Paytrail.
Conta Paytrail: você precisa do seu Merchant ID e da Secret key, exibidos no Painel do Comerciante da Paytrail (detalhes da conta ou da integração). Para testes nenhuma conta é necessária: o modo de teste utiliza a conta de teste pública da Paytrail. Os métodos de pagamento em si são ativados na sua conta Paytrail.
Chave de licença VibeFox: adquirida 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_paytrail_gateway para /wp-content/plugins/ por FTP.
2. Clique em Activate.
3. Abra as configurações: WooCommerce > Settings > Payments > Paytrail > Manage, ou clique em Settings sob o nome do plugin na página Plugins.
4. Digite a sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.
5. Para testar o plugin primeiro, marque a opção Test mode. Para pagamentos reais, desmarque-a e informe seu Merchant ID e a Secret key. Nenhuma URL de callback precisa ser configurada na Paytrail.
6. Ative Enable/Disable e salve as alterações.
Configuração
Todas as configurações ficam em uma única página: WooCommerce > Settings > Payments > Paytrail. Acima dos campos, a página exibe Test mode is active. enquanto o modo de teste estiver ativado. No modo de produção, ela avisa se o Merchant ID ou a Secret key estiverem ausentes, além de alertar se a moeda da loja não for EUR. Em ambos os casos, a Paytrail não é exibida na finalização de compra. Na lista de métodos de pagamento, a Paytrail é sinalizada como necessitando de configuração enquanto o modo de produção não possuir credenciais.
Ao salvar, um Merchant ID que contenha caracteres diferentes de dígitos não é salvo: um erro é exibido e o valor anterior é mantido.
General
Enable/Disable: Enable Paytrail ativa ou desativa o método de pagamento. Padrão: desativado.
Title: o título exibido aos clientes durante a finalização de compra. Padrão: Paytrail.
Description: o texto exibido aos clientes durante a finalização de compra. Padrão: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.
API credentials
Seu Merchant ID e sua Secret key são exibidos no Painel do Comerciante da Paytrail (detalhes da conta ou da integração). Há suporte apenas para pagamentos em EUR.
Test mode: Use the Paytrail test account. Novos pagamentos usam a conta de teste pública da Paytrail (Merchant ID 375917) em vez das suas próprias credenciais. Nenhum dinheiro real é cobrado. Os clientes veem Test mode: no real payment will be made. na finalização de compra. A Secret key da conta de teste é pública, de modo que qualquer pessoa poderia simular um pagamento para um pedido criado no modo de teste. Nunca deixe o modo de teste ativado em uma loja em produção. Padrão: desativado.
Merchant ID: seu Merchant ID da Paytrail (apenas dígitos). Usado quando o modo de teste está desativado.
Secret key: sua Secret key da Paytrail. Usada quando o modo de teste está desativado.
Os callbacks e reembolsos sempre utilizam as credenciais do modo em que o pagamento foi realizado, de modo que alternar entre teste e produção não afeta pedidos mais antigos.
Orders
Esta seção exibe a URL de callback, que se parece com https://your-site/wc-api/ptg_paytrail/. A Paytrail confirma cada pagamento de servidor para servidor nessa URL. Ela é enviada com cada pagamento, de modo que nada precisa ser configurado no painel da Paytrail, mas o site deve estar acessível pela internet.
Order status after payment: o status de um pedido pago. O status é definido em uma única etapa, para que o cliente receba apenas um conjunto de e-mails.
Advanced
Debug log: Log API requests and callbacks. Gravado em WooCommerce > Status > Logs, origem wcp_paytrail_gateway, sem dados pessoais ou chaves. Os erros são sempre registrados. Padrão: desativado.
Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. Desativar o plugin nunca exclui nada. Sem os dados de transação da Paytrail, reembolsos de pedidos antigos não serão mais possíveis pelo WooCommerce. Padrão: desativado.
Finalização de compra
O cliente escolhe o método de pagamento (por padrão Paytrail) e faz o pedido. O plugin cria um pagamento na Paytrail para o total do pedido em euros e envia as linhas do pedido junto com ele: produtos, frete e taxas, cada um com sua alíquota de IVA com uma casa decimal. As linhas sempre somam exatamente o valor do pagamento; eventuais diferenças de arredondamento são absorvidas em uma linha ou enviadas como uma linha de Rounding. Os endereços de faturamento e entrega só são enviados quando estão completos, e valores longos são encurtados de acordo com os limites da Paytrail. O idioma da página de pagamento é finlandês, sueco ou inglês, seguindo a configuração regional da loja.
O cliente é redirecionado para a página de pagamento da Paytrail, escolhe um método de pagamento ativado na sua conta Paytrail e efetua o pagamento. Em seguida, a Paytrail confirma o pagamento de duas formas: retorna o cliente para a sua loja e chama a URL de callback de servidor para servidor. Ambos só são aceitos com uma assinatura válida gerada com as credenciais daquela tentativa de pagamento e apenas para a tentativa criada para aquele pedido. O valor pago é comparado com o total do pedido. O pedido só é marcado como pago depois que a Paytrail o confirma dessa forma. O plugin processa estes status da Paytrail:
Após um pagamento bem-sucedido, o cliente visualiza a página de pedido recebido. Após um pagamento cancelado ou com falha, o cliente é direcionado para a página Pay for order com a mensagem The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Se o pagamento ainda não foi concluído, a mensagem será The Paytrail payment has not been completed yet. You can try again or choose another payment method.
Caso a Paytrail não consiga iniciar o pagamento, o cliente visualiza uma mensagem curta, por exemplo Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (credenciais incorretas) ou Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. O motivo técnico é adicionado às notas do pedido e ao log. Pedidos acima do valor máximo da Paytrail não podem ser pagos com a Paytrail.
Um pagamento na Paytrail não pode ser cancelado pela API. Se o cliente iniciar um novo pagamento e depois também pagar em uma página de pagamento mais antiga ainda aberta, o segundo pagamento é reportado nas notas do pedido como um duplicado a reembolsar.
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. Ele é compatível com o High-Performance Order Storage (HPOS) do WooCommerce.
O cliente escolhe o método de pagamento na página da Paytrail, e não na sua finalização de compra. O plugin não possui tokenização ou cartões salvos, não suporta WooCommerce Subscriptions, modelo de marketplace, ativação manual de faturas nem relatórios de liquidação.
Pedidos e reembolsos
Status dos pedidos
Pending payment: o pagamento na Paytrail foi criado e o cliente ainda não pagou. A nota do pedido mostra o ID da transação da Paytrail, o valor e o modo.
Processing or Completed: o pagamento foi confirmado. O status segue o valor de Order status after payment. A nota do pedido mostra a transação, o método de pagamento usado na Paytrail e o valor. O ID da transação é o ID de transação da Paytrail.
On hold: o pagamento está pendente no provedor (fatura ou pagamento com atraso), o valor pago difere do total do pedido, o pagamento chegou após o pedido ter sido cancelado ou um pagamento de teste foi recebido enquanto a loja estava em produção (sem dinheiro real). A nota do pedido explica o motivo. Verifique o pedido e, em seguida, processe-o ou reembolse o pagamento.
Failed: a tentativa de pagamento mais recente falhou ou foi cancelada pelo cliente. O cliente pode pagar novamente.
Callbacks repetidos ou em paralelo nunca criam notas duplicadas, reduções de estoque duplicadas ou e-mails em duplicidade. Se uma segunda tentativa de um pedido já pago for quitada, o pedido não é alterado novamente; uma nota Duplicate payment solicita que você realize o reembolso no Painel do Comerciante da Paytrail.
Reembolsos
Abra o pedido, clique em Refund, insira o valor e clique em Refund via Paytrail (o botão exibe o seu Title). Há suporte a reembolsos totais e parciais, exclusivamente para valores (sem itens de linha de reembolso). O botão fica disponível apenas para pedidos com pagamento Paytrail confirmado. O reembolso utiliza as credenciais do modo em que o pagamento foi realizado, de modo que para pagamentos reais as credenciais de produção devem estar preenchidas.
Se o método de pagamento não aceitar reembolsos diretos, o plugin inicia automaticamente um reembolso por e-mail: a Paytrail envia um e-mail ao cliente para que ele informe uma conta bancária. Isso exige um e-mail de faturamento no pedido. A nota do pedido informa que tipo de reembolso foi iniciado.
Um reembolso pode ser concluído imediatamente ou processado mais tarde. A confirmação posterior da Paytrail é adicionada como uma nota. Caso a Paytrail não tenha conseguido concluir o reembolso, uma nota informará que o dinheiro não foi devolvido ao cliente: faça o reembolso por outro canal e exclua o registro de reembolso do WooCommerce. Se a Paytrail recusar o reembolso de imediato, o WooCommerce exibirá o erro e nenhum reembolso será registrado.
Reembolsos feitos no Painel do Comerciante da Paytrail não são sincronizados de volta para o WooCommerce.
Chave de licença
O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica na parte superior de WooCommerce > Settings > Payments > Paytrail. Cole a chave em License key e clique em Activate. O bloco mostra o status, como a data até a qual a licença é válida e o seu domínio. Use Check now para conferir o status novamente, Change key para inserir outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre a sua conta no vibefox.net.
Uma chave funciona em um único domínio. Remover a chave de um site não libera o seu slot de domínio. Libere o slot na sua conta vibefox.net.
Sem uma chave ativa, a Paytrail não é exibida aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente verá This payment method is not available. Please choose another one. Administradores de loja autenticados ainda conseguem ver a forma de pagamento, sinalizada como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de adquirir uma chave. Um lembrete é mostrado 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 normalmente.
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
A Paytrail não aparece na finalização de compra: verifique se a licença está ativa, se Enable/Disable está ativado e se Test mode está ativado ou se Merchant ID e Secret key estão preenchidos. Certifique-se de que a moeda da loja (ou a moeda do pedido na página Pay for order) seja EUR. A página de configurações exibe um aviso para cada um desses problemas.
O pagamento foi feito, mas o pedido continua com o status Pending payment: o callback não consegue alcançar o seu site e o cliente não retornou à loja. A URL de callback mostrada na seção Orders deve estar acessível pela internet (sem modo de manutenção, autenticação básica HTTP ou firewall no caminho).
O callback ou o retorno responde Payment verification failed.: a assinatura é inválida ou o pagamento não pertence a uma tentativa de pagamento deste pedido. O pedido não é alterado. Verifique se a sua Secret key está correta e se pertence ao Merchant ID informado.
O pagamento não é criado: a nota do pedido e o log exibem o erro da Paytrail, por exemplo Paytrail API error (401): … em caso de credenciais incorretas. Ative Debug log e verifique em WooCommerce > Status > Logs, origem wcp_paytrail_gateway.
O Merchant ID não é salvo: ele deve conter apenas dígitos. Copie-o novamente do Painel do Comerciante da Paytrail.
O pedido está com status On hold: leia a nota do pedido. O motivo pode ser um pagamento pendente ou com atraso, valor pago divergente, pagamento efetuado após cancelamento ou um pagamento de teste recebido no modo de produção.
O reembolso falha: leia a mensagem. This order has no confirmed Paytrail payment. Refund it manually. significa que não há nenhum pagamento confirmado da Paytrail para reembolsar. Uma mensagem sobre credenciais de produção ausentes significa que o pagamento foi realizado em modo de produção e as credenciais de produção não estão preenchidas. Se o método de pagamento aceitar apenas reembolsos por e-mail, o pedido precisa ter um e-mail de faturamento.
Ganchos para desenvolvedores: o filtro ptg_payment_request altera a requisição de pagamento antes que ela seja assinada e enviada; o filtro ptg_icon altera o ícone da finalização de compra.
O bloco de licença mostra um erro: siga as orientações exibidas no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere um slot na sua conta 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. Caso o servidor de licenças não possa ser acessado, o plugin continuará funcionando com base no último status conhecido.
Desinstalação
A desativação do 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 excluídos. As configurações da forma de pagamento, o log deste plugin e os dados da Paytrail armazenados nos pedidos (tentativas de pagamento, dados da transação, registros de reembolso) só serão excluídos se a opção Delete data on uninstall estiver ativada. Caso contrário, eles permanecerão disponíveis para uma posterior reinstalação. Pedidos existentes mantêm suas notas de pagamento e os IDs de transação; sem os dados da Paytrail, pedidos antigos não poderão mais ser reembolsados a partir do WooCommerce.
A Paytrail é uma marca registrada de seu respectivo titular. Este plugin não é afiliado nem endossado pela Paytrail.