VibeFox PagSeguro for PrestaShop — Ajuda

Requisitos

PrestaShop: 8.0 a 9.x.

PHP: 8.0 ou superior. O módulo não instala em versões anteriores do PHP.

Moeda: Real brasileiro (BRL). O método de pagamento só é exibido para carrinhos em BRL.

HTTPS: sua loja precisa estar acessível pela internet por HTTPS para que o PagBank possa enviar as notificações de pagamento.

Conta do PagBank: um token de produção para pagamentos reais e um token de sandbox para testes. Produção: faça login na sua conta do PagBank, abra Venda online > Integrações e clique em Gerar token; o PagBank envia o token por e-mail. Sandbox: crie uma conta sandbox no portal de desenvolvedores do PagBank e copie o token dela. Tokens de sandbox e de produção funcionam apenas no próprio ambiente.

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

3. Informe 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. Informe o token de sandbox e, para receber pagamentos reais, o token de produção.

5. Ative Enable / Disable e clique em Save. Faça pagamentos de teste com Sandbox Mode ativado e depois desative-o para receber pagamentos reais.

Na instalação, o módulo cria dois status de pedido, Awaiting PagBank payment e PagBank 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; a moeda BRL precisa continuar permitida para o módulo.

Configuração

Todas as configurações estão na página do módulo: Modules > Module Manager > VibeFox PagSeguro Gateway > Configure. Cada seção tem seu próprio botão Save, que salva a página inteira. Acima dos campos, a página mostra o modo atual: SANDBOX MODE (os pagamentos são criados no sandbox do PagBank, sem cobranças reais) ou LIVE (os pagamentos são criados com o token de produção). Ela avisa quando o token do modo atual está faltando (o método de pagamento fica oculto no checkout) e quando a moeda padrão da loja não é BRL (o método de pagamento não é oferecido para carrinhos em outras moedas).

PagSeguro / PagBank

Enable / Disable: Enable PagSeguro/PagBank payments liga ou desliga o método de pagamento. Padrão: desligado.

Title: o nome do método de pagamento que o cliente vê no checkout. Também é o nome do método de pagamento salvo no pedido. Padrão: PagSeguro / PagBank. Obrigatório.

Description: o texto exibido abaixo do método de pagamento no checkout. Padrão: Pay securely via PagSeguro/PagBank. You will be redirected to complete your payment.

Conta do PagBank

A seção explica onde obter os tokens e traz links para a sua conta do PagBank e para a página do PagBank sobre tokens.

Sandbox Mode: Enable sandbox/test mode (no real charges). Novos pagamentos vão para o sandbox do PagBank com o token de sandbox, e os clientes veem SANDBOX MODE — Using test environment. No real charges. abaixo do método de pagamento. As consultas de status e os reembolsos de um pedido sempre usam o ambiente e o token com os quais o pagamento foi criado. Padrão: ligado.

Sandbox token: o token de sandbox do PagBank. Usado enquanto o modo sandbox estiver ligado.

Production token: o token de produção do PagBank (Bearer). Usado quando o modo sandbox está desligado. Mantenha-o em segredo.

Tokens salvos nunca são exibidos novamente. O campo fica vazio e mostra Saved — leave empty to keep it. Digite um novo valor apenas para alterá-lo.

Clear saved tokens: marque um token e clique em Save para removê-lo. Um campo vazio mantém o valor salvo.

Notificações de pagamento

Notification URL: cada pagamento informa ao PagBank para onde enviar as mudanças de status, por isso não há nada a configurar no PagBank. A seção mostra a URL. Com URLs amigáveis, ela tem este formato: https://your-shop/module/wcp_pagseguro_gateway/webhook. O endereço precisa estar acessível pela internet por HTTPS.

Notificações que trazem o cabeçalho x-authenticity-token são verificadas com o token do ambiente em que o pagamento foi criado; uma assinatura inválida é rejeitada. O corpo da notificação em si nunca é confiável: o módulo sempre lê o checkout e o pedido do PagBank pela API do PagBank (status, valor, moeda) antes de criar ou alterar um pedido. Sem notificações, o pedido é criado quando o cliente volta à loja depois de pagar.

Avançado

Debug log: Log API requests and notifications grava os detalhes em logs/wc_psg_debug.log.php, na pasta do módulo. O arquivo não pode ser aberto pela web. Os logs não contêm tokens nem dados de clientes. Erros são sempre registrados. Padrão: desligado.

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

Delete Data on Uninstall: quando ligado, desinstalar o módulo remove as configurações do gateway e o log. Pedidos, suas referências do PagBank (necessárias para reembolsos) e os status de pedido são sempre mantidos. Padrão: desligado.

Finalização da compra

Na etapa de pagamento, o cliente escolhe o método de pagamento (por padrão PagSeguro / PagBank) e confirma. O módulo cria um checkout no PagBank para o total do carrinho em BRL como um único item, Order # com o número do carrinho e o nome da sua loja, e envia o cliente para a página de pagamento do PagBank. Nome e e-mail do cliente, o CPF ou CNPJ do campo Identification number ou VAT number do endereço e um telefone brasileiro são preenchidos quando a loja os tem; o cliente pode completar ou corrigir essas informações na página do PagBank. O cliente paga com os métodos habilitados na sua conta do PagBank, por exemplo cartão de crédito, PIX ou boleto. A página de pagamento expira em 120 minutos. Nesse ponto, ainda não existe pedido.

Depois de pagar, o cliente volta para a sua loja. O pedido só é marcado como pago depois que o PagBank confirma: o módulo lê o pagamento pela API do PagBank quando a notificação chega ou quando o cliente retorna, e um retorno sozinho nunca marca um pedido como pago. O pedido é então criado e o cliente vê a página de confirmação do pedido com Your payment with PagBank has been received. Para um boleto ou PIX gerado, ou um pagamento em análise, a página mostra Your PagBank payment is awaiting confirmation (boleto / PIX / analysis). The order will be confirmed as soon as PagBank reports the payment. Se esse pagamento for recusado ou cancelado depois, a página mostra Your PagBank payment was not completed. Please contact us about this order. Se o PagBank ainda não tiver confirmado o pagamento quando o cliente voltar, aparece uma página Payment confirmation com We are confirming your payment with PagBank. The order will be updated automatically — please do not pay again. e um botão Check again.

Se o pagamento não foi concluído, o cliente volta ao checkout com The PagBank payment was not completed. You can pay the order again below., The PagBank payment page has expired. You can pay the order again below. ou The payment was declined by PagBank. Please try again with another card or payment method. O carrinho é mantido. Se um pedido que aguardava boleto ou PIX foi cancelado, o cliente vê The PagBank payment was cancelled, so the order was cancelled.

Quando o cliente paga de novo, o checkout aberto no PagBank é reaproveitado se o valor e o ambiente forem os mesmos e ele não expirar em até 10 minutos. Caso contrário, o checkout anterior é desativado e não pode mais ser pago. Um pagamento feito antes, na página anterior, continua valendo para o carrinho, e o pedido é criado em vez de um novo pagamento.

Se o PagBank não conseguir iniciar o pagamento, o cliente permanece no checkout com uma mensagem curta, por exemplo PagBank did not accept your billing details (CPF/CNPJ). Please check them and try again. ou Could not connect to PagBank. Please try again in a moment. O motivo técnico é gravado no log.

As notificações funcionam com a loja em modo de manutenção e não são bloqueadas pela restrição de países da sua loja.

O módulo não tem formulário de cartão na loja, não guarda cartões, não oferece assinaturas nem cobranças recorrentes, não faz pagamentos divididos nem marketplaces. Os métodos de pagamento e os parcelamentos são os configurados na sua conta do PagBank.

Pedidos e reembolsos

Status do pedido

Ainda sem pedido: o cliente foi enviado ao PagBank e não pagou, o cartão foi recusado ou a página de pagamento expirou. Só existe o carrinho, e o cliente pode pagar de novo.

Payment accepted: o pagamento foi confirmado com o valor e a moeda esperados. O pagamento é registrado com o charge ID do PagBank como ID da transação, e uma nota mostra o valor, o método de pagamento e o charge ID.

Awaiting PagBank payment: um boleto ou PIX foi gerado e aguarda pagamento, ou o pagamento está em análise. O pedido passa para Payment accepted quando o PagBank informa que foi pago.

PagBank payment on hold: o PagBank informou valor ou moeda diferentes do carrinho (por exemplo, o carrinho foi alterado depois que a página de pagamento foi criada), um pagamento chegou depois que o pedido foi cancelado (verifique o estoque e depois conclua o pedido ou estorne o pagamento no PagBank), ou um pagamento com cartão foi autorizado, mas não capturado (capture-o no PagBank). A nota explica. O dinheiro efetivamente recebido é registrado no pedido.

Payment error: um pagamento que estava aguardando ou em análise foi recusado.

Canceled: um pagamento que estava aguardando, por exemplo um boleto ou PIX vencido, foi cancelado.

Refunded: o pagamento foi reembolsado integralmente, pelo módulo ou no painel do PagBank.

Cada status do PagBank é aplicado uma única vez, então notificações ou retornos repetidos não adicionam notas nem mudam status. Se chegar um segundo pagamento para um pedido que já está pago, o pedido não é alterado e uma nota pede que você estorne o duplicado no PagBank.

Bloco «PagBank payment»

A página do pedido mostra um bloco PagBank payment com o checkout do PagBank, os IDs do pedido e do charge no PagBank, o método de pagamento, o status, o valor pago e reembolsado, um selo Sandbox para pagamentos de sandbox, o histórico de reembolsos e as PagBank notes do pedido.

Reembolsos

No bloco PagBank payment, digite o valor (o valor ainda não reembolsado já vem preenchido), opcionalmente um motivo, e clique em Refund via PagBank. Confirme a pergunta Refund this amount through PagBank? This cannot be undone. Reembolsos totais e parciais são aceitos. É preciso ter permissão para editar pedidos; o acesso às páginas de módulos não é necessário. O limite é o valor cobrado pelo PagBank, então, depois de uma divergência de valor, você pode reembolsar até o que o cliente realmente pagou, e não o total do pedido. O reembolso é enviado no ambiente e com o token em que o pagamento foi feito. Um reembolso só é registrado quando o PagBank o confirma; caso contrário, o bloco mostra o erro, por exemplo PagBank refund failed: ... ou PagBank did not confirm the refund, e nada é registrado. Reembolsos de pagamentos por boleto e reembolsos parciais de PIX seguem as regras do PagBank. Um reembolso bem-sucedido é adicionado ao histórico de reembolsos e às notas, com o charge ID. Um reembolso total coloca o pedido em Refunded; um reembolso parcial não altera o status. Os reembolsos ficam disponíveis depois que o PagBank informa o pagamento como pago.

O módulo não gera notas de crédito. Os botões de reembolso padrão do PrestaShop na página do pedido não devolvem dinheiro pelo PagBank.

Reembolsos feitos no painel do PagBank são percebidos na próxima notificação: um reembolso total coloca o pedido em Refunded, um reembolso parcial adiciona uma nota com o valor reembolsado, e você pode registrar o reembolso no pedido manualmente.

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 PagSeguro Gateway é o primeiro bloco de Modules > Module Manager > VibeFox PagSeguro Gateway > Configure, acima das configurações. Informe 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-pagseguro e o link Manage licenses and domains in your account, que abre a sua conta do 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 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 do vibefox.net.

Sem uma chave ativa, o PagBank não é mostrado 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 do PrestaShop não sabe que você está logado no back office, então o meio de pagamento fica oculto para você também: você pode configurar o módulo antes de comprar uma chave, mas não 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, e os reembolsos funcionam.

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

O PagBank não aparece no checkout: verifique se a licença está ativa, se Enable / Disable está ligado, se o token do modo atual está preenchido (Sandbox token no modo sandbox, Production token no modo live) e se a moeda do carrinho é BRL. A página de configurações mostra um aviso quando o token está faltando ou a moeda da loja não é BRL. Em Payment > Preferences, verifique se o módulo está permitido para BRL, para o país do cliente e para o grupo do cliente.

O pagamento foi feito, mas nenhum pedido foi criado: o PagBank ainda não informou o pagamento e o cliente não voltou à loja. O pedido é criado assim que a notificação chega. Verifique se a sua loja está acessível pela internet por HTTPS no endereço da Notification URL, e ative o Debug log para ver as notificações.

A notificação responde Invalid signature: o x-authenticity-token não corresponde ao token do ambiente em que o pagamento foi feito, ou esse token não está salvo. Verifique se o token correto está nas configurações.

A notificação responde Verification failed, retry later: a API do PagBank não pôde ser acessada, o token do ambiente do pagamento está faltando, ou o carrinho estava sendo processado por outra requisição ao mesmo tempo. O PagBank reenvia a notificação.

A notificação responde Order not found: a notificação é de um carrinho que não foi pago com este módulo nesta loja. Nada é alterado.

O cliente vê PagBank payments are temporarily unavailable. Please choose another payment method.: o token do modo atual está faltando ou o PagBank o rejeitou.

O cliente vê PagSeguro/PagBank only accepts payments in Brazilian Real (BRL).: o carrinho está em outra moeda.

O pedido está em PagBank payment on hold: leia as notas no bloco PagBank payment (veja Status do pedido), compare os valores no PagBank e depois conclua o pedido ou estorne o pagamento.

O reembolso falha com uma mensagem sobre o token: o pagamento foi feito no sandbox ou na produção, e o token desse ambiente está faltando ou foi rejeitado. Informe o token correto e tente novamente.

Desinstalação

Vá em Modules > Module Manager, abra o menu ao lado de VibeFox PagSeguro 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 ligado, as configurações do gateway e o log são removidos. Se estiver desligado, todas as configurações são mantidas para uma reinstalação posterior. Os pagamentos e reembolsos do PagBank dos pedidos e os status de pedido Awaiting PagBank payment e PagBank payment on hold são sempre mantidos, para que pedidos pagos antes ainda possam ser reembolsados após uma reinstalação. Pedidos existentes mantêm suas notas de pagamento e IDs de transação.

PagSeguro e PagBank são marcas registradas de seus respectivos titulares. Este módulo não é afiliado nem endossado pelo PagSeguro ou pelo PagBank.