VibeFox Paysera for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou posterior. O módulo se recusa a ser instalado em versões anteriores do PHP.

Projeto Paysera: você precisa do ID do projeto e da senha do projeto (sign key) do seu projeto Paysera. Os métodos de pagamento que o cliente vê são os ativados neste projeto. Nada precisa ser configurado na Paysera para o callback: a URL dele é enviada em cada solicitação de pagamento.

Loja acessível: os pedidos são criados pelo callback da Paysera, então sua loja deve estar acessível pela internet, e não atrás de um login, de uma autenticação básica ou de um firewall. O callback funciona mesmo quando a loja está em modo de manutenção.

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

3. Insira sua chave de licença VibeFox no campo License key, no 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 Project password da sua conta Paysera (veja Configuração).

5. Opcional: ative Allow test payments no projeto Paysera e Test payments no módulo para testar o fluxo sem cobrar dinheiro. Desative-os antes de começar a vender.

6. Ative Enable/Disable e clique em Save.

Ao instalar, o módulo cria dois status de pedido: Awaiting Paysera payment e Paysera 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.

Configuração

Todas as configurações ficam na página do módulo: Modules > Module Manager > VibeFox Paysera Payment > Configure. Cada seção tem o próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra Paysera is hidden at checkout until the project ID and the project password are entered. enquanto um dos dois estiver faltando, e Test mode is on: customers are not charged. Turn off "Test payments" and select "Production" before accepting real orders. enquanto os pagamentos de teste ou o sandbox estiverem ativos.

Paysera

Enable/Disable: Enable Paysera Payment liga ou desliga o método de pagamento. Padrão: off.

Title: o nome do método de pagamento que o cliente vê no checkout. Ele também é o nome do método de pagamento salvo no pedido. Padrão: Paysera. Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely via Paysera.

Projeto Paysera

Encontre o ID do projeto e a senha do projeto na sua conta Paysera, em Projects and activities, no seu projeto, em General project settings.

Callback URL: o endereço que a Paysera usa para confirmar cada pagamento. Com URLs amigáveis, ele tem esta forma: https://your-shop/module/wcp_paysera_payment/callback, possivelmente com um código de idioma. Ele é enviado automaticamente com cada pagamento, então nada precisa ser configurado na Paysera, mas deve estar acessível pela internet. Os pedidos são criados somente por esses callbacks assinados.

Project ID: o ID numérico do seu projeto Paysera. Só são aceitos dígitos: qualquer outro valor gera o erro Project ID must be a number: the numeric ID of your Paysera project. e nada é salvo.

Project password: a senha do projeto (sign key). Ela assina as solicitações de pagamento e verifica os callbacks da Paysera. A senha salva nunca é mostrada novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um valor novo somente se quiser alterá-la.

Clear saved password: marque Project password e clique em Save para remover a senha salva. Um campo vazio mantém o valor salvo.

Testes

Test payments: envia os pagamentos em modo de teste, então nenhum dinheiro é cobrado. A Paysera devolve um pagamento de teste bem-sucedido sem cobrar o cliente. Ative antes Allow test payments nas configurações do projeto Paysera. Enquanto esta opção estiver ativa, os pagamentos de teste marcam os pedidos como pagos; quando estiver desativada, um pagamento de teste coloca o pedido em espera. Padrão: off. Enquanto estiver ativa, os clientes veem TEST MODE — no money will be charged. abaixo do método de pagamento.

Environment: para onde o cliente é enviado. Mantenha Production para um projeto Paysera normal, inclusive para pagamentos de teste. Padrão: Production.

Avançado

Debug log: grava os eventos de pagamento em logs/wc_psr_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos são sempre gravados; as demais etapas, apenas enquanto esta opção estiver ativa. Senhas e dados de clientes nunca são gravados. Padrão: off.

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

Delete data: quando ativa, desinstalar o módulo remove as configurações do módulo e o log. Os dados de pedidos (pedidos, registros de pagamento da Paysera, status de pedido) são sempre mantidos. Padrão: off.

Finalização da compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Paysera) e confirma o pedido. O módulo cria uma solicitação de pagamento assinada com o total do carrinho na unidade mínima da moeda do carrinho, o nome, o e-mail e o endereço de cobrança do cliente, e o idioma da página da loja (lituano, letão, estoniano, russo, alemão, polonês; caso contrário, inglês). O cliente é enviado à janela de pagamento da Paysera e escolhe lá um banco, um cartão ou outro método. Nesse momento ainda não existe nenhum pedido.

A Paysera confirma o pagamento com um callback servidor a servidor. O pedido só é marcado como pago depois que a Paysera confirma com um callback assinado; o retorno do cliente à loja nunca cria nem paga um pedido. Quando o cliente volta após o callback, é exibida a página padrão de confirmação do pedido. Se o banco aceitou a ordem de pagamento, mas ainda não a executou, o pedido é criado em Awaiting Paysera payment e a página mostra Paysera is confirming your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Para um pedido em espera, a página mostra Your payment is being reviewed. We will contact you if anything else is needed.

Se o cliente voltar antes do callback, uma página Payment confirmation explica que o pedido será criado assim que a Paysera confirmar o pagamento e oferece Check again e Back to checkout.

Se o cliente cancelar na janela da Paysera, volta ao checkout com The Paysera payment was cancelled. You can try again or choose another payment method. Se a Paysera informar que o pagamento não foi executado, a mensagem é The payment was not completed. You can try again or choose another payment method. O carrinho é mantido nos dois casos. Se o carrinho já tiver um pedido, uma nova tentativa vai direto para a confirmação do pedido, em vez de um segundo pagamento.

Se o pagamento não puder ser iniciado, o cliente permanece no checkout com Paysera payments are temporarily unavailable. Please choose another payment method. ou, para um total de pedido inválido, com This order cannot be paid via Paysera. O motivo é gravado no log.

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

O módulo não oferece reembolsos pelo Back Office, nem escolha de banco ou método de pagamento na página de checkout, nem assinaturas, cartões salvos ou serviços de entrega ou courier da Paysera.

Pedidos

Status do pedido

No order yet: o cliente foi enviado para a Paysera e o callback ainda não chegou, ou o cliente cancelou. Existe apenas o carrinho.

Payment accepted: a Paysera confirmou o pagamento com o valor e a moeda correspondentes. O pagamento é registrado com o ID da solicitação na Paysera como ID da transação, e uma nota mostra a solicitação e o método de pagamento, marcada como (TEST — no money charged) nos pagamentos de teste.

Awaiting Paysera payment: a Paysera aceitou a ordem de pagamento, mas o banco ainda não a executou. O pedido passa para Payment accepted quando a Paysera confirma o pagamento.

Paysera payment on hold: o pagamento precisa de revisão manual. O valor ou a moeda pagos diferem do carrinho ou do total do pedido; um pagamento TEST chegou enquanto Test payments estava desativado (nenhum dinheiro foi cobrado); ou o pagamento foi confirmado depois que o cliente o havia cancelado. O pagamento não é registrado. A nota explica isso, e o bloco da Paysera pede que você verifique o pagamento na sua conta Paysera e depois defina o pedido como Payment accepted, ou cancele-o e reembolse o pagamento na Paysera.

Cancelled: um pagamento confirmado mais tarde para um pedido cancelado não altera o status dele. Uma nota pede para restaurar o pedido (defini-lo como Payment accepted) ou reembolsar o pagamento na Paysera. Um pagamento TEST posterior ou uma divergência de valor em um pedido cancelado também adiciona apenas uma nota.

Se chegar outro pagamento bem-sucedido para um pedido que já está pago, o pedido não é alterado, e uma nota pede para reembolsar o duplicado na sua conta Paysera. Os outros status da Paysera (pagamento não executado, informações adicionais) apenas adicionam uma nota.

Bloco de pagamento da Paysera

A página do pedido mostra um bloco Paysera payment com o ID do pedido na Paysera (o número do carrinho e a tentativa), o ID da solicitação na Paysera, o ambiente e a marca TEST payment, o status do pagamento, os valores solicitado e pago, o método de pagamento e as notas do módulo.

Reembolsos

Reembolsos pelo Back Office não são suportados: o protocolo da janela de pagamento da Paysera não tem API de reembolso. Faça os reembolsos na sua conta Paysera. Quando a Paysera informa um reembolso, uma nota com o valor reembolsado é adicionada ao pedido, e o status do pedido não muda. Registre o reembolso no PrestaShop manualmente, se necessário.

Chave de licença

O módulo funciona com uma chave de licença VibeFox de vibefox.net. O bloco de licença License — VibeFox Paysera Payment é o primeiro bloco da página Modules > Module Manager > VibeFox Paysera Payment > 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 informar outra chave, e Remove key, para remover a chave desta loja. Abaixo deles ficam a linha Product: presta-payment-paysera 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 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 ú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 de domínio. Libere a vaga na sua conta vibefox.net.

Sem uma chave ativa, a Paysera não é mostrada aos clientes no checkout. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. A vitrine da loja 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 no checkout. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados pelo callback.

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 informada, 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

A Paysera não aparece no checkout: verifique se a licença está ativa, se Enable/Disable está ligado e se Project ID e Project password foram preenchidos. A página de configurações mostra um aviso enquanto algum deles estiver faltando. 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 feito, mas nenhum pedido foi criado: o pedido é criado pelo callback da Paysera, não pelo retorno do cliente. Verifique se a sua loja está acessível pela internet no Callback URL mostrado nas configurações (e não atrás de um login, de uma autenticação básica ou de um firewall), e consulte o campo Log na página do módulo.

O callback responde Invalid signature: a Project password não corresponde ao projeto, ou o callback não vem da Paysera. Copie a senha do projeto novamente. Se você alterou o projeto ou a senha, pagamentos iniciados antes da mudança não podem mais ser verificados.

O callback responde Project ID mismatch: o Project ID nas configurações é diferente do projeto que fez o pagamento.

O callback responde Order not found: o carrinho no callback não tem um pagamento da Paysera nesta loja, por exemplo porque o pagamento foi iniciado em outra loja com o mesmo projeto.

O callback responde Gateway not configured, Busy ou Temporary error: o ID ou a senha do projeto está vazio, outro callback do mesmo carrinho ainda está em execução, ou o pedido não pôde ser criado (por exemplo, porque o módulo está desativado). A Paysera tenta o callback novamente. Ative Debug log para ver o motivo.

A Paysera recusa a janela de pagamento ou diz que o projeto não existe: verifique Environment. Um projeto Paysera normal funciona apenas com Production; o Sandbox exige um projeto criado no ambiente sandbox da Paysera.

O pagamento de teste não paga o pedido: um pagamento TEST só paga um pedido enquanto Test payments estiver ativo. Caso contrário, o pedido é colocado em espera com uma nota informando que nenhum dinheiro foi cobrado. Ative também Allow test payments no projeto Paysera.

Um pedido está em Paysera payment on hold com uma nota sobre divergência de valor ou moeda: a Paysera confirmou um pagamento cujo valor ou moeda difere do total do carrinho, por exemplo porque o carrinho foi alterado em outra aba depois que o cliente iniciou o pagamento. Compare o pagamento na sua conta Paysera e aceite o pedido ou reembolse o pagamento manualmente. Um pagamento correto posterior para o mesmo pedido o marca como pago.

O cliente vê Paysera payments are temporarily unavailable: consulte o campo Log. O ID ou a senha do projeto podem estar vazios, ou um dos endereços da loja enviados à Paysera tem mais de 255 caracteres.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Paysera Payment e escolha Uninstall. A chave de licença e o status da licença deste módulo são sempre removidos. Se Delete data estiver ativo, 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 futura. Os registros de pagamento da Paysera e os status de pedido Awaiting Paysera payment e Paysera payment on hold são sempre mantidos. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Paysera é uma marca registrada de seu respectivo proprietário. Este módulo não é afiliado nem endossado pela Paysera.