VibeFox Paytrail for PrestaShop — Ajuda
Requisitos
PrestaShop: 8.0 a 9.x.
PHP: 8.0 ou superior. O módulo não é instalado em versões anteriores do PHP.
Moeda: EUR. A Paytrail aceita somente euros. Para um carrinho em outra moeda, o método de pagamento fica oculto na finalização de compra. Os valores são enviados em centavos.
Acesso à internet para a sua loja: a Paytrail confirma cada pagamento com um callback servidor para servidor, por isso a loja deve estar acessível pela internet. Sem os callbacks, os pedidos ainda são criados quando o cliente retorna da Paytrail.
Conta na Paytrail: você precisa do seu Merchant ID e da sua Secret key, exibidos no Painel do Comerciante da Paytrail (dados da conta ou da integração). Para testes, não é necessária nenhuma conta: o modo de teste usa a conta pública de testes da Paytrail. Os próprios métodos de pagamento são ativados na sua conta Paytrail.
Chave de licença VibeFox: adquirida em vibefox.net. Uma chave funciona em um único 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, mais tarde, localize VibeFox Paytrail 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. Para testar primeiro o módulo, ative Test mode. Para pagamentos reais, desative-o e informe o seu Merchant ID e a sua Secret key. Não é preciso configurar nenhuma URL de callback na Paytrail.
5. Ative Enable/Disable e clique em Save.
Ao ser instalado, o módulo cria dois status de pedido, Awaiting Paytrail payment e Paytrail 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á-lo em Payment > Preferences.
Configuração
Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox Paytrail 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 mostra Test mode is active. Payments use the public Paytrail test account — no real money is charged. enquanto o modo de teste estiver ativo. No modo real, ela avisa quando o Merchant ID ou a Secret key estão ausentes, ou quando o Merchant ID é a conta pública de testes 375917. Também avisa quando a moeda da loja não é EUR. Em todos esses casos a Paytrail não é exibida na finalização de compra.
Ao salvar, um Merchant ID que contenha qualquer coisa além de dígitos não é salvo, e aparece o erro Paytrail merchant ID must contain digits only. The previous value was kept.. O campo Title não pode ficar vazio.
Paytrail
Enable/Disable: Enable Paytrail ativa ou desativa o método de pagamento. Padrão: off.
Title: o título exibido aos clientes na finalização de compra. Também é o nome do método de pagamento salvo no pedido. Padrão: Paytrail. Obrigatório.
Description: o texto exibido aos clientes abaixo do método de pagamento na finalização de compra. Padrão: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.
Credenciais de API
Seu Merchant ID e sua Secret key são exibidos no Painel do Comerciante da Paytrail (dados da conta ou da integração). A seção tem um link para o Painel do Comerciante. São aceitos somente pagamentos em EUR.
Test mode: usa a conta pública de testes da Paytrail (Merchant ID 375917) para os novos pagamentos, em vez das suas credenciais. Nenhum dinheiro real é cobrado e não são necessárias chaves. Os clientes veem Test mode: no real payment will be made. abaixo do método de pagamento. A Secret key da conta de testes é pública, então qualquer pessoa poderia simular um pagamento feito no modo de teste. Nunca deixe o modo de teste ativado em uma loja real. Padrão: off.
Merchant ID: o seu Merchant ID da Paytrail (somente dígitos). Usado quando o modo de teste está desativado.
Secret key: a sua Secret key da Paytrail. Usada quando o modo de teste está desativado. A chave salva nunca mais é exibida. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor somente para alterá-la.
Clear saved secret key: marque Secret key e clique em Save para remover a chave salva. Um campo vazio mantém o valor salvo.
Callbacks e reembolsos sempre usam as credenciais do modo em que o pagamento foi feito, então alternar entre teste e real não quebra pedidos antigos.
Pedidos
Callback URL: mostra a URL em que a Paytrail confirma cada pagamento servidor para servidor. Com URLs amigáveis, ela fica assim: https://your-shop/module/wcp_paytrail_gateway/callback. Ela é enviada em cada pagamento, então nada precisa ser configurado no painel da Paytrail, mas a loja precisa estar acessível pela internet.
Order status after payment: o status de um pedido pago.
Pagamentos pendentes aguardam em Awaiting Paytrail payment. Divergências de valor e outros problemas sempre vão para Paytrail payment on hold.
Avançado
Debug log: registra requisições à API e callbacks em logs/ptg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Dados pessoais e chaves não são registrados. Erros e avisos são sempre registrados. Padrão: off.
Log: mostra o tamanho e as entradas mais recentes do log. Clique em Clear log para esvaziá-lo.
Delete data on uninstall: quando ativado, desinstalar o módulo remove as configurações e o log. Desativar o módulo nunca apaga nada. Os dados de transação da Paytrail dos pedidos são sempre mantidos, porque os reembolsos de pedidos antigos precisam deles. Padrão: off.
Finalização de compra
Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Paytrail) e confirma. O módulo cria um pagamento Paytrail pelo total do carrinho em euros e envia com ele os itens do pedido: produtos após as regras do carrinho, frete e embrulho para presente, cada um com a sua alíquota de IVA de uma casa decimal. Os itens sempre somam exatamente o valor do pagamento; uma diferença de arredondamento é incorporada a um item ou enviada como um item Rounding. Os endereços de cobrança e de entrega são enviados somente quando estão completos, e valores longos são abreviados para os limites da Paytrail. O idioma da página de pagamento é finlandês, sueco ou inglês, seguindo o idioma do carrinho. Nesse ponto ainda não existe pedido.
O cliente é direcionado à página de pagamento da Paytrail, escolhe um método de pagamento ativado para a sua conta Paytrail e paga. Em seguida, a Paytrail confirma o pagamento duas vezes: devolve o cliente à sua loja e chama a URL de callback servidor para servidor. As duas confirmações são aceitas somente com assinatura válida feita com as credenciais daquela tentativa de pagamento, e somente para uma tentativa criada para aquele carrinho. O valor pago é comparado com o total do carrinho. O pedido só é marcado como pago depois que a Paytrail confirma dessa forma. O módulo trata estes status da Paytrail:
Após um pagamento bem-sucedido, o cliente vê a página padrão de confirmação do pedido com Your Paytrail payment has been received. Para um pagamento pendente, a página mostra Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. Se o callback estiver registrando o pagamento exatamente naquele momento, uma página Payment confirmation pede ao cliente que não pague novamente e oferece um botão Check again.
Após um pagamento cancelado ou com falha, o cliente volta à finalização de compra com The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Se o pagamento ainda não tiver sido concluído, a mensagem é The Paytrail payment has not been completed yet. You can try again or choose another payment method. O carrinho é mantido. Um retorno que não pode ser verificado exibe Payment verification failed. e não altera nada.
Se a Paytrail não conseguir iniciar o pagamento, o cliente permanece na finalização de compra com 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 é gravado no log. Um total fora dos limites da Paytrail exibe This order total cannot be paid with Paytrail. Please choose another payment method.
Um pagamento na Paytrail não pode ser cancelado pela API. Cada nova tentativa do carrinho é um novo pagamento na Paytrail. Se o cliente também pagar uma página de pagamento antiga que ainda esteja aberta, o segundo pagamento é informado no pedido como duplicado a reembolsar.
O callback funciona enquanto a loja está em modo de manutenção e não é bloqueado pela restrição de país da sua loja.
O cliente escolhe o método de pagamento na página da Paytrail, e não na sua finalização de compra. O módulo não tem tokenização de cartões nem cartões salvos, assinaturas, shop-in-shop, ativação manual de faturas nem relatórios de liquidação.
Pedidos e reembolsos
Status do pedido
Ainda sem pedido: o cliente foi enviado à Paytrail e não pagou, ou a Paytrail ainda não confirmou o pagamento. Só existe o carrinho.
Payment accepted or Delivered: o pagamento foi confirmado. O status segue Order status after payment. O pagamento é registrado com o ID da transação na Paytrail, e uma nota mostra a transação, o método de pagamento usado na Paytrail e o valor.
Awaiting Paytrail payment: o pagamento está pendente no provedor (fatura ou pagamento com atraso). O pedido passa para o status de pago quando a Paytrail confirma o pagamento, ou para Payment error quando ele falha.
Paytrail payment on hold: o valor pago difere do total do pedido (o valor realmente pago é registrado), o pagamento chegou depois que o pedido havia sido cancelado, ou um pagamento de teste foi recebido enquanto a loja está em produção (sem dinheiro real, nada é registrado). A nota explica o motivo. Verifique o pedido e depois processe-o ou reembolse o pagamento.
Payment error: um pagamento pendente falhou ou foi cancelado.
Refunded: o pagamento foi totalmente reembolsado pelo módulo.
Callbacks repetidos ou simultâneos nunca criam um segundo pedido nem notas duplicadas. Se uma segunda tentativa de um carrinho já pago for paga, o pedido não muda; uma nota Duplicate payment pede que você a reembolse no Painel do Comerciante da Paytrail.
Bloco de pagamento Paytrail
A página do pedido mostra um bloco Paytrail payment com o ID da transação, o modo (um selo TEST mode para pagamentos de teste), o método de pagamento, o status na Paytrail, o valor pago e reembolsado, o formulário de reembolso, o histórico de reembolsos, as tentativas de pagamento do carrinho e as Paytrail notes do pedido.
Reembolsos
No bloco Paytrail payment, informe o valor (o valor ainda não reembolsado é preenchido), opcionalmente um motivo para a nota do pedido, e clique em Refund via Paytrail. Confirme a pergunta Refund this amount through Paytrail? This cannot be undone. Reembolsos totais e parciais são aceitos, apenas por valor. Você precisa da permissão para editar pedidos; o acesso às páginas de Módulos não é necessário. Você pode reembolsar até o valor que a Paytrail efetivamente cobrou, então, após uma divergência de valor, o limite é o que o cliente pagou, e não o total do pedido. O reembolso usa as credenciais do modo em que o pagamento foi feito, então, para um pagamento real, as credenciais reais precisam estar configuradas. Os reembolsos ficam disponíveis assim que a Paytrail confirma o pagamento.
Se o método de pagamento não oferecer suporte a reembolsos diretos, o módulo 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 o e-mail do cliente no pedido. A nota indica qual tipo de reembolso foi iniciado.
Um reembolso pode ser concluído na hora ou processado depois. A confirmação posterior da Paytrail é adicionada como nota. Se a Paytrail não conseguir concluir o reembolso, uma nota informa que o dinheiro não foi devolvido ao cliente, e o reembolso deixa de contar como reembolsado; devolva o valor ao cliente por outro meio. Se a Paytrail rejeitar o reembolso imediatamente, o bloco exibe o erro e nenhum reembolso é registrado. Um reembolso total define o pedido como 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 Paytrail. Os reembolsos feitos no Painel do Comerciante da Paytrail não são sincronizados de volta com o PrestaShop.
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 Paytrail Gateway é o primeiro bloco da página Modules > Module Manager > VibeFox Paytrail 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 ficam a linha Product: presta-payment-paytrail e o link Manage licenses and domains in your account, que abre a sua conta 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 Paytrail 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 loja 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 pelos callbacks e pelo retorno do cliente, e os reembolsos funcionam.
Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte precisam de uma 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 inserção da chave, 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
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 (e não a conta pública de testes 375917). Verifique se a moeda do carrinho é EUR. 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. A página de configurações exibe um aviso quando faltam credenciais ou a moeda da loja está errada.
O pagamento foi feito, mas nenhum pedido foi criado: o callback não consegue chegar à sua loja, e o cliente não voltou à loja. A Callback URL exibida na seção Pedidos precisa estar acessível pela internet (sem autenticação básica nem firewall no caminho).
Callback ou retorno responde Payment verification failed.: a assinatura é inválida, ou o pagamento não pertence a uma tentativa de pagamento do carrinho. Nada é alterado. Verifique se a Secret key está correta e pertence ao Merchant ID.
O callback responde Temporarily unavailable: o pedido estava sendo confirmado por outra requisição naquele mesmo momento, ou o pedido não pôde ser criado (por exemplo, o módulo está desativado). A Paytrail chama novamente. Veja o campo Log para o motivo.
O cliente vê um erro ao escolher a Paytrail: veja o campo Log na página do módulo. Por exemplo, Paytrail API error (401) significa credenciais incorretas. Ative o Debug log para mais detalhes.
O Merchant ID não é salvo: ele deve conter somente dígitos. Copie-o novamente do Painel do Comerciante da Paytrail.
O pedido está em Paytrail payment on hold: leia as notas no bloco Paytrail payment. O motivo é um valor pago diferente, um pagamento após o cancelamento ou um pagamento de teste em modo real.
O reembolso falha: leia a mensagem. This order has no confirmed Paytrail payment. Refund it manually. significa que não há pagamento confirmado na Paytrail para reembolsar. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. significa que o pagamento foi feito em modo real e as credenciais reais não estão configuradas. Invalid refund amount: at most … significa que o valor é maior que o saldo ainda reembolsável. Se o método de pagamento aceitar apenas reembolsos por e-mail, o pedido precisa do e-mail do cliente.
Hook para desenvolvedores: o hook actionWcpPaytrailPaymentRequest altera a requisição de pagamento antes de ela ser assinada e enviada.
Desinstalação
Acesse Modules > Module Manager, abra o menu ao lado de VibeFox Paytrail Gateway e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data on uninstall estiver ativado, as configurações e o log são removidos. Se estiver desativado, todas as configurações são mantidas para uma reinstalação posterior. As transações e reembolsos da Paytrail e os status de pedido Awaiting Paytrail payment e Paytrail 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.
Paytrail é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado à Paytrail nem endossado por ela.