VibeFox Przelewy24 for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo se recusa a ser instalado em versões mais antigas do PHP.

Moeda: o carrinho deve estar em PLN, EUR, GBP ou CZK. Em outras moedas, o método de pagamento fica oculto na finalização do pedido. O carrinho é cobrado na própria moeda; o módulo não converte moedas.

Conta na Przelewy24: você precisa de uma conta de comerciante na Przelewy24 e dos dados de API: o Merchant ID, a chave de API (chamada report key no painel da Przelewy24), a chave CRC e, se a sua loja tiver um ID próprio, o POS ID (Shop ID). Você os encontra no painel de comerciante da Przelewy24, em panel.przelewy24.pl, em My data > API data and configuration. As chaves de sandbox vêm de uma conta sandbox separada, em sandbox.przelewy24.pl/panel. Não há mais nada a configurar no painel da Przelewy24: o módulo envia a sua URL de notificação com cada pagamento. Sua loja precisa estar acessível pela internet, porque a Przelewy24 envia para ela as notificações de pagamento.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona em um único 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 VibeFox Przelewy24 Payment depois na lista de módulos e clique em Configure.

3. Insira 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. Insira as chaves de sandbox (Merchant ID, chave de API, chave CRC; o POS ID só se for diferente do Merchant ID), ative Enable/Disable, clique em Save e faça um pagamento de teste no modo sandbox.

5. Insira as chaves de produção, desative Test Mode e clique em Save para aceitar pagamentos reais.

Na instalação, o módulo cria o status de pedido Przelewy24 payment on hold. Em seguida, 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 Przelewy24 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 avisos quando algo está faltando. Enquanto o sandbox estiver ativo: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. Quando as chaves do modo atual estão incompletas: Enter the Sandbox Merchant ID, API key and CRC key - until then Przelewy24 is not shown at checkout. (ou o mesmo para as chaves Live). Quando a Przelewy24 não aceita a moeda padrão da sua loja, o aviso informa a moeda e as moedas aceitas. Depois de salvar, os avisos acompanham imediatamente o novo modo e as novas chaves. Espaços e quebras de linha copiados junto com as chaves do painel da Przelewy24 são removidos ao salvar.

Przelewy24

Enable/Disable: Enable Przelewy24 Payment ativa ou desativa o método de pagamento. Padrão: desativado.

Title: o nome do método de pagamento que o cliente vê na finalização do pedido. Também é o nome do método de pagamento salvo no pedido. Padrão: Przelewy24. Obrigatório: ao salvar com o título vazio, aparece Enter a title for the payment method.

Description: o texto exibido abaixo do método de pagamento na finalização do pedido. Padrão: Pay with BLIK, online bank transfer or card via Przelewy24.

Credenciais de API

A seção explica onde encontrar as chaves (My data > API data and configuration no painel de comerciante da Przelewy24) e traz links para panel.przelewy24.pl e sandbox.przelewy24.pl/panel.

Test Mode: usa o sandbox da Przelewy24 (sandbox.przelewy24.pl) e as chaves Sandbox. Nenhum dinheiro real é cobrado. Desative para aceitar pagamentos reais em secure.przelewy24.pl com as chaves Live. Padrão: ativado. Enquanto estiver ativo, os clientes veem Sandbox mode - no real money is charged abaixo do método de pagamento.

Chaves Live

Live Merchant ID: o seu ID de comerciante na Przelewy24, somente números.

Live POS ID (optional): o Shop ID (posId). Deixe vazio se for igual ao Merchant ID.

Live API key (report key): a chave de API do painel da Przelewy24. Ela é usada para a autenticação na API.

Live CRC key: usada para assinar as requisições enviadas à Przelewy24 e para verificar a assinatura das notificações da Przelewy24.

Chaves Sandbox

Sandbox Merchant ID: o Merchant ID da sua conta sandbox na Przelewy24.

Sandbox POS ID (optional): o Shop ID (posId) da conta sandbox. Deixe vazio se for igual ao Merchant ID.

Sandbox API key (report key): a chave de API da conta sandbox.

Sandbox CRC key: a chave CRC da conta sandbox, usada para assinar as requisições e verificar as notificações do sandbox.

As chaves de API e CRC salvas nunca são mostradas novamente. O campo fica vazio e exibe Saved - leave empty to keep it. Digite um novo valor somente se quiser alterá-lo.

Clear saved secrets: marque uma chave e clique em Save para removê-la. Um campo vazio mantém o valor salvo.

As chaves Live e as do sandbox são diferentes. O Merchant ID e o POS ID devem conter apenas dígitos; enquanto o Merchant ID, a chave de API e a chave CRC do modo atual não forem inseridos, o método de pagamento não aparece na finalização do pedido. Um pagamento iniciado em um modo é sempre verificado e reembolsado com as chaves desse modo, mesmo depois de você trocar de modo; por isso, mantenha as chaves do modo antigo enquanto os pagamentos dele estiverem em aberto ou puderem ser reembolsados.

Notificações de pagamento

Notification URL: o endereço que recebe as notificações de pagamento da Przelewy24. Com URLs amigáveis, ele tem a forma https://your-shop/module/wcp_przelewy24_payment/notify, possivelmente com um código de idioma como /en/. O módulo envia esta URL à Przelewy24 em cada pagamento e em cada reembolso, então nada precisa ser configurado no painel da Przelewy24. A URL precisa estar acessível pela internet: não pode haver firewall nem autenticação HTTP na frente dela. Ela continua funcionando enquanto a loja está em modo de manutenção e não é bloqueada pela restrição de países da sua loja. Sem notificações, o pagamento ainda é confirmado quando o cliente volta à loja (veja Finalização do pedido); se o cliente não voltar, nenhum pedido é criado.

Avançado

Debug Log: grava eventos técnicos (números de carrinho, IDs de transação da P24, erros) em logs/wc_p24_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Erros e avisos, como notificações rejeitadas ou uma verificação ou reembolso com falha, são sempre registrados; ative a opção para registrar também cada etapa. Chaves, corpos de requisições e dados pessoais nunca são registrados. Padrão: desativado.

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. Pedidos e os dados de pagamento deles na Przelewy24 nunca são excluídos. Padrão: desativado.

Finalização do pedido

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão Przelewy24, com o logotipo da P24) e confirma o pedido. O módulo registra uma transação na Przelewy24 pelo total do carrinho na moeda do carrinho, com o e-mail, o nome e o país de cobrança do cliente, e a descrição Cart # com o número do carrinho e o nome da sua loja. Cada tentativa de pagamento recebe um ID de sessão próprio. O cliente é enviado à página de pagamento da Przelewy24 e paga com BLIK, transferência bancária online, cartão ou outro método habilitado para a sua conta na Przelewy24. A página de pagamento é exibida no idioma do carrinho do cliente, se a Przelewy24 o suportar; caso contrário, em inglês. Nesse ponto, ainda não existe pedido.

O pedido só é marcado como pago depois que a Przelewy24 confirma. A Przelewy24 envia à sua loja uma notificação assinada. O módulo verifica a assinatura com a chave CRC, o Merchant ID e o POS ID; se a sessão foi registrada para este carrinho e no mesmo modo; e se o valor e a moeda coincidem com a tentativa de pagamento e com o total atual do carrinho. Só então verifica a transação com a Przelewy24 (a Przelewy24 só credita pagamentos verificados) e cria o pedido em Payment accepted. Webhooks sem assinatura válida são rejeitados.

Depois de pagar, o cliente volta à sua loja. Se a notificação ainda não tiver chegado, o módulo pede à Przelewy24 o status da transação com uma requisição autenticada de servidor para servidor (no máximo uma vez a cada 10 segundos por carrinho) e aplica as mesmas verificações. A página de retorno sozinha nunca marca um pedido como pago. Quando o pagamento é confirmado, o cliente vê a página padrão de confirmação do pedido. Enquanto não estiver confirmado, uma página Payment confirmation mostra We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: com um botão Check again e um botão Pay again, que abre a finalização do pedido. O carrinho é mantido, e um pagamento feito depois, em uma página antiga da Przelewy24 do mesmo carrinho, continua sendo aceito. Se o pedido estiver em espera, a página de confirmação mostra Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Se o pagamento não puder ser iniciado, o cliente permanece na finalização do pedido com uma mensagem curta: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (o motivo vai para o log), Payment gateway is not configured properly. Please contact the administrator. (faltam as chaves do modo atual), uma mensagem informando que a Przelewy24 não pode aceitar pagamentos na moeda do carrinho, ou The order total must be greater than zero. Um carrinho que já tem um pedido não é enviado de novo à Przelewy24; o cliente vai para a confirmação do pedido.

O módulo não oferece cartões salvos nem pagamentos com um clique, assinaturas ou pagamentos recorrentes, não permite escolher o método de pagamento P24 (por exemplo, um campo de código BLIK) na finalização do pedido, não tem widgets de parcelamento e não envia o conteúdo do carrinho à Przelewy24.

Pedidos e reembolsos

Status do pedido

No order yet: o cliente foi enviado à Przelewy24 e não pagou, ou o pagamento ainda não foi confirmado. Existe apenas o carrinho.

Payment accepted: o pagamento foi verificado. Ele é registrado com o ID do pedido na P24 como ID da transação, e uma nota mostra o ID do pedido na P24, o valor e o modo. Cada pagamento é aplicado uma única vez.

Przelewy24 payment on hold: o valor ou a moeda informados pela Przelewy24 diferem do carrinho (por exemplo, o carrinho foi alterado depois que o pagamento foi iniciado); o pagamento não foi confirmado e a nota informa isso. Ou o pagamento chegou e foi verificado para um pedido que havia sido cancelado; o pedido não é reaberto silenciosamente, e a nota pede que você o envie ou reembolse o pagamento. Verifique o pagamento no painel da Przelewy24. Se, depois de uma divergência, chegar mais tarde um pagamento correto de outra tentativa para um pedido em espera, o pedido passa para Payment accepted.

Refunded: o pagamento foi totalmente reembolsado pelo módulo.

Se chegar um segundo pagamento para um carrinho cujo pedido já está pago ou reembolsado (um link de pagamento antigo, duas abas do navegador), ele não é confirmado, então a Przelewy24 não o credita. Uma nota no pedido pede que você o verifique no painel da Przelewy24 e, se necessário, devolva o valor ao comprador.

Bloco de pagamento da Przelewy24

A página do pedido mostra um bloco Przelewy24 payment com o ID do pedido na P24, a sessão, o ambiente (um selo Sandbox para pagamentos de sandbox), o status do pagamento e como ele foi verificado (notificação ou retorno), os valores pagos e reembolsados, o formulário de reembolso, o histórico de reembolsos e as Payment notes do pedido.

Reembolsos

No bloco Przelewy24 payment, informe o valor (o valor ainda não reembolsado já vem preenchido), opcionalmente um motivo, e clique em Refund via Przelewy24. Confirme a pergunta Refund this amount through Przelewy24? This cannot be undone. Reembolsos totais e parciais são aceitos, até o valor ainda não reembolsado. Você precisa ter permissão para editar pedidos; o acesso às páginas de módulos não é necessário. O reembolso é enviado no modo em que o pagamento foi feito (sandbox ou produção), então as chaves desse modo precisam estar configuradas. Os reembolsos ficam disponíveis depois que a Przelewy24 verifica o pagamento.

A Przelewy24 processa os reembolsos de forma assíncrona. O bloco mostra Refund of … requested at Przelewy24. The result will be added as an order note., o histórico de reembolsos mostra o status requested e uma nota é adicionada. O resultado chega depois na URL de notificação: o status passa para completed com a nota Przelewy24: refund of … completed., ou para rejected com uma nota informando que o dinheiro não foi devolvido ao comprador. Um reembolso total define o pedido como Refunded no momento em que é solicitado; um reembolso parcial não altera o status. Se um reembolso for rejeitado, verifique-o no painel da Przelewy24; o status do pedido não é revertido automaticamente.

Se a Przelewy24 não aceitar a solicitação de reembolso, o bloco mostra Przelewy24 refund failed: com o motivo, e nenhum reembolso é registrado. 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 Przelewy24, e os reembolsos feitos diretamente no painel da Przelewy24 não são adicionados ao pedido.

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 Przelewy24 Payment é o primeiro bloco de Modules > Module Manager > VibeFox Przelewy24 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 inserir outra chave e Remove key para remover a chave desta loja. Abaixo ficam a linha Product: presta-payment-przelewy24 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 ú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 em vibefox.net.

Sem uma chave ativa, a Przelewy24 não é exibida aos clientes na finalização do pedido. Se mesmo assim um pagamento for iniciado, 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ê: pode configurar o módulo antes de comprar uma chave, mas não testá-lo na finalização do pedido. Um lembrete aparece em Modules > Module Manager, na aba Alerts. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo verificados e confirmados, e os reembolsos funcionam.

Quando uma licença expira, o módulo continua funcionando, mas atualizações e suporte exigem 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 Przelewy24 não aparece na finalização do pedido: verifique se a licença está ativa, se Enable/Disable está ativado, se o Merchant ID, a chave de API e a chave CRC do modo atual estão preenchidos (as chaves Sandbox enquanto Test Mode estiver ativado, caso contrário as chaves Live; Merchant ID e POS ID apenas com dígitos) e se a moeda do carrinho é PLN, EUR, GBP ou CZK. Os avisos no topo das configurações indicam o problema. 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. Desenvolvedores podem alterar a lista de moedas com o hook actionWcpPrzelewy24SupportedCurrencies (somente moedas com duas casas decimais habilitadas para a sua conta na Przelewy24).

O pagamento foi feito, mas nenhum pedido foi criado: a notificação da Przelewy24 não chegou à sua loja e o cliente não voltou à loja. Verifique se a Notification URL está acessível pela internet (sem firewall nem autenticação HTTP na frente) e se o Merchant ID, o POS ID e a chave CRC do modo do pagamento estão corretos. Notificações rejeitadas são gravadas no log mesmo com o Debug Log desativado; veja o campo Log na página do módulo.

Como a loja responde às notificações: uma notificação processada, repetida ou desconhecida recebe a resposta HTTP 200. Caso contrário, a Przelewy24 a reenvia depois: 400 (dados ausentes ou malformados), 401 Invalid signature (chave CRC errada, outro Merchant ID ou POS ID), 401 Invalid signature for this payment (notificação assinada com as chaves do outro modo em relação ao pagamento), 405 (não é uma requisição POST), 500 Verification failed (a verificação com a Przelewy24 falhou; uma nota é adicionada ao pedido uma vez, se ele existir), 500 Order could not be created (por exemplo, o módulo está desativado; a notificação seguinte cria o pedido sem nova verificação) e 503 Busy, retry later (o carrinho estava sendo confirmado por outra requisição no mesmo momento).

O cliente vê Payment error: Przelewy24 could not start the payment: a Przelewy24 rejeitou a transação, geralmente por chaves erradas do modo atual (as chaves sandbox funcionam só no modo sandbox, as chaves live só no modo live). O erro da Przelewy24 está no log.

O pedido está em Przelewy24 payment on hold depois do pagamento: leia as notas no bloco Przelewy24 payment. O valor ou a moeda diferia do carrinho, ou o pagamento chegou para um pedido que havia sido cancelado. Verifique o pagamento no painel da Przelewy24 e então processe o pedido ou reembolse o pagamento.

Um reembolso falha: This order has no verified Przelewy24 payment. Cannot process refund. significa que o pedido não foi pago por um pagamento verificado da Przelewy24. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (ou o mesmo para Live) significa que as chaves do modo do pagamento foram removidas; insira-as novamente. Invalid refund amount significa que o valor está vazio, não é um número ou é maior que o valor ainda não reembolsado.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox Przelewy24 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 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 dados de pagamento da Przelewy24 dos pedidos (sessões, IDs de pedido na P24, reembolsos) e o status Przelewy24 payment on hold são sempre mantidos, então pedidos pagos antes podem ser reembolsados mesmo após uma reinstalação. Os pedidos existentes mantêm suas notas de pagamento e IDs de transação.

Przelewy24 é uma marca registrada de seu respectivo titular. Este módulo não é afiliado nem endossado pela Przelewy24.