Integrando Prestashop com PagBank

Com o módulo PagBank, sua loja PrestaShop se conecta de forma completa à principal solução de pagamentos do Brasil. Desenvolvido com os rigorosos padrões de segurança do PCI DSS e alinhado às melhores práticas da PrestaShop, o módulo garante proteção dos dados e um checkout ágil e intuitivo para seus clientes. Acesse nosso repositório oficial no GitHub, baixe o módulo PagBank e impulsione suas vendas com a melhor solução do mercado!

Novo módulo

O módulo PagSeguroPro foi descontinuado. Ele foi substituído pelo novo módulo PagBank.

Para atualizar o módulo em sua loja, você deve:

Instalar o novo módulo PagBank.
Desativar o módulo PagSeguroPro que foi descontinuado.

Você encontra mais informações sobre o processo de instalação nas próximas seções desta página. A imagem abaixo apresenta o dashboard após instalar o novo módulo e desabilitar o módulo descontinuado.

Compatibilidade

A seguir, você encontra uma lista das características de compatibilidade do novo módulo PagBank.

Este módulo não utiliza Override.
Compatível com PrestaShop 1.6.x, 1.7.x e 8.x.
Compatível com PHP 5.2.0 ao 8.1.18.
Desenvolvido, testado e homologado com base na API v.4 do PagBank.
Requer a biblioteca cURL ativa na hospedagem.
Obrigatório o uso de certificado SSL com o protocolo TLS 1.2 ou superior.

Instalação

Para realizar a instalação do módulo PagBank, você precisará enviar o arquivo pagbank.zip. Para realizar essa operação, siga os passos a seguir:

Acesse o repositório do módulo no GitHub.
Faça o download dos arquivos. Para isso, clique em Code e depois selecione a opção Download Zip.
Após fazer o download, descompacte o arquivo em seu computador e verifique se dentro da pasta de arquivos descompactados está o arquivo pagbank.zip.
Após ter o arquivo em pagbank.zip, você deve acessar o dashboard da sua conta PrestaShop e navegar até Módulos → Gerenciador de Módulos.
Clique em Enviar um módulo e selecione o arquivo pagbank.zip baixado anteriormente.

Ao finalizar os passos descritos acima o novo módulo estará instalado.

👍
Otimize a sua aplicação
Sempre que você instalar ou atualizar o módulo, acesse Parâmetros Avançados -> Desempenho e clique em Limpar Cache. Isso irá garantir que todos os arquivos sejam atualizados no cache da PrestaShop.

Configuração

O processo de configuração do módulo envolve 6 passos principais e um passo complementar e não obrigatório. Esses passos são:

Cadastro e adesão do App
Configuração do App
Configuração de meios de pagamento
Mapeamento de status de pedidos
Debug & Logs
Tarefa CRON
Estorno parcial ou total de pedidos (passo extra não obrigatório)

Cada uma dessas etapas é detalhada nas seções abaixo.

1. Cadastro e adesão do App

O cadastramento no App é o primeiro passo para tornar a sua integração funcional. Para isso, você deve acessar Módulos → Gerenciar Módulos, buscar pelo módulo PagBank e clicar no botão Configurar.

Existem três opções disponíveis para cadastro, as quais diferem nas taxas cobrados e períodos de recebimento:

App D14
App D30
App Tax

Ao acessar a página de configuração você terá acesso às informações atualizadas. A imagem abaixo é um exemplo da interface que você utilizará para fazer a escolha entre as opções disponíveis.

Para iniciar o processo de adesão, clique em Cadastrar e prossiga com o passo-a-passo indicado.

2. Configurações do App

Após realizar o cadastro, ative o toogle associado a opção Ambiente de Produção. No campo Tipo de Credencial, selecione qual App deve validar e processar os pagamentos.

3. Configurações de pagamento

O módulo PagBank disponibiliza três opções de meio de pagamento que você pode configurar e oferecer aos seus clientes:

Cartão de Crédito (+30 bandeiras)
Boleto Bancário
Pix
Pagar com PagBank (Wallet)

Além das opções de meios de pagamento, você também pode configurar descontos para as cobranças.

Ao acessar a página de configuração do módulo e navegar até a seção Configurações de Pagamento, você pode habilitar essas opções de forma individual. No entanto, cada meio de pagamento possui configurações adicionais que precisam ser especificadas. Essas configurações são apresentadas a seguir.

3.1. Cartão de Crédito

Para disponibilizar a opção de pagar com Cartão de Crédito aos seus clientes, você deve navegar até a seção de Configurações de Pagamento.

Marque a opção Cartão de Crédito como Sim para ativar o meio de pagamento e visualizar as configurações relacionadas.

Na sequência configure as seguintes opções:

Quantidade máxima de parcelas: selecione 1 para pagamentos à vista ou de 2 até 12 parcelas para que pagamentos parcelados sejam aceitos.
Quantidade de parcelas sem juros.
Valor da parcela mínima: define o valor mínimo da parcela aceita pela loja no momento do parcelamento da compra.
Comportamento da parcela mínima: define o comportamento do checkout caso o valor da parcela seja inferior ao valor estabelecido para o valor da parcela mínima.
Compra com 1 Click: dá ao cliente a opção de salvar o Cartão de Crédito para futuras compras. O Cartão é criptografado e armazenado pelo PagBank através do processo de Tokenização.
Tipo de Captura: Escolha entre captura automática ou manual (pré-autorização).

3.1.1. Cartão de Crédito - Compra com 1 Click

Na opção Compra com 1 Click, o cliente poderá salvar o Cartão de Crédito para futuras compras. O Cartão é criptografado e armazenado pelo PagBank através do processo de Tokenização.

Após realizar a primeira compra com o cartão salvo ele ficará disponível para seleção na tela de checkout, como demonstrado na imagem abaixo:

3.1.2. Cartão de Crédito - Pré-autorização

Na Captura Automática, o valor total da transação é debitado imediatamente do saldo do cartão de crédito de forma automatizada.

Na Captura Manual (Pré-autorização), o valor da transação fica reservado no saldo do cartão até que você decida capturar um valor parcial ou total. Caso capture um valor menor, o restante será automaticamente estornado. Exemplo: se a transação for de R$ 1.000,00 e você capturar R$ 800,00, os R$ 200,00 restantes serão devolvidos ao saldo do cartão.

Quando o pedido for gerado com o status Pagamento Autorizado, basta acessar o histórico do pedido e informar o valor que deseja capturar, como demonstrado no exemplo abaixo:

3.2. Boleto Bancário

Para disponibilizar a opção de pagar com Boleto Bancário aos seus clientes, você deve navegar até a seção de Configurações de Pagamento e mudar a opção Boleto Bancário para Sim. Ao fazer isso, as opções de configurações desse método de pagamento serão apresentadas. A seguir você encontra a lista de configurações disponíveis com algumas dicas para sua configuração:

Prazo de vencimento do boleto: define a validade do Boleto após a sua geração. O padrão é de 2 dias.
Texto descritivo para o boleto: forneça um texto a ser inserido no Boleto.

📘
Ao configurar a opção de Boleto Bancário, você precisa configurar a Tarefa Cron para o cancelamento do Boleto após seu vencimento.

3.3. PIX

Para disponibilizar a opção de pagar com PIX aos seus clientes, você deve navegar até a seção de Configurações de Pagamento e mudar a opção PIX para Sim. Ao fazer isso, as opções de configurações desse método de pagamento serão apresentadas.

O método PIX permite que você configure apenas a opção do Prazo limite de pagamento via PIX, que irá definir o tempo para a expiração dessa opção de pagamento. Por padrão, esse valor é de 30 minutos.

📘
Ao configurar a opção do PIX, você precisa configurar a Tarefa Cron para o cancelamento do PIX após seu vencimento.

3.4 - Pagar com PagBank (Wallet)

Ative a opção Pagar com PagBank para habilitar esse meio de pagamento e acessar suas configurações. Com essa opção, o cliente pode pagar usando o saldo da conta PagBank ou um cartão de crédito salvo no super app.

📘
Configure a Tarefa Cron para garantir o cancelamento automático de pagamentos via PagBank.

Atualmente, a opção Pagar com PagBank apresenta as seguintes limitações:

O prazo de expiração do QR Code/link de pagamento é fixo em 24 horas.
Não é possível aplicar desconto para pagamentos à vista.
Não há suporte para pré-autorização em pagamentos com cartão de crédito.
O cliente pode pagar tanto com saldo em conta quanto com cartão de crédito. Não é possível restringir a apenas uma opção.

3.5. Opções de Descontos

Para configurar as opções de desconto, você deve navegar até a seção de Configurações de Pagamento e selecionar o tipo de desconto que deseja aplicas às transações. Você tem a opção de escolher entre:

Descontos de valor fixo. Nesse caso você irá definir um valor em reais a ser aplicado a todas as compras.
Descontos percentuais. Estipule um valor percentual de desconto que será aplicado a todas as compras.

Além de definir o tipo e o montante do desconto, você tem a opção de escolher a quais meios de pagamento esse desconto será aplicado. Para isso, você deve ativar as opções desejadas dentre:

Desconto no Cartão de Crédito (1x). No Cartão e Crédito o desconto é calculado e exibido na primeira parcela.
Desconto no Boleto Bancário.
Desconto no Pix.

4. Mapeamento de status de pedidos

Para facilitar o gerenciamento de pedidos, oferecemos a opção de mapeamento de status, permitindo a criação de status personalizados conforme suas necessidades.

Para criar novos status, acesse Compras > Status.

Após criar os status, vá até a configuração do módulo para mapeá-los com os status disponíveis no sistema.

Os seguintes status estão disponíveis:

Pagamento Aceito
Pagamento Autorizado
Pedido Cancelado
Pedido Estornado
Pagamento em Análise
Aguardando Pagamento

5. Debug & Logs

Dependendo do problema que você está enfrentando, uma ação diferente deve ser realizada. Nesta seção são apresentadas as opções que você pode utilizar para encontrar e resolver problemas.

Para acessar as opções apresentadas, abra a página de configuração do módulo e navegue até a seção Debug & Logs.

5.1. Debug para soluções de problemas

Para uma análise técnica mais aprofundada, a fim auxiliar no desenvolvimento ou identificar eventuais conflitos de JavaScript na loja virtual, marque a opção Exibir parâmetros no Console do navegador? como Sim.

👍
Otimize o seu sistema
Sempre que você instalar ou atualizar o módulo, acesse a tab Parâmetros Avançados -> Desempenho e clique em Limpar Cache. Isso irá garantir que todos os arquivos sejam atualizados no cache da PrestaShop.`

5.2. Registro de transações e gerenciamento de Logs

Para ter acesso aos Logs, você primeiro deve ativar a opção Gerar LOGs completos?, selecionando a opção Sim. Assim, o módulo irá registrar tudo o que é enviado e recebido entre a sua loja e o PagBank.

Para visualizar os registros de Logs acesse PagBank → PagBank → Logs, clique em Ver para analisar os detalhes do que foi enviado e recebido entre a sua loja e o PagBank.

📘
Código de Referência
O Código de Referência da transação no PagBank é composto pelo ID do Carrinho + APP utilizado + Número randômico.
Exemplo de Código de Referência: 78895.TAX.177850.

📘
Proteção dos dados
Dados sensíveis do cliente como endereço, nome e sobrenome ou razão social, cpf/cnpj e telefone não são armazenados em Log.
Todas as transações via Cartão de Crédito são Tokenizadas e também não são armazenadas em Log.

Para maiores detalhes a respeito do pedido, você deve acessar PagBank → PagBank → Transações. Depois clique em Ver. As mesmas informações também estão disponíveis no histórico do pedido, que apresenta os dados atualizados em tempo real das interações entre a sua loja e o PagBank.

### 5.3. Limpeza do Banco de Dados

A opção Apagar tabelas do banco? disponível na seção de Debug & Logs deve permanecer sempre desativada. Você irá ativar essa opção, marcando a opção como Sim, apenas se você desejar desinstalar o módulo.

🚧
Utilize esse recurso com cautela.

Ativando esta opção, todos os registros de transações, incluindo informações básicas como ID do pedido na loja e no PagBank, ID do cliente, ID do carrinho, etc., e especialmente os registros de Logs, que contêm detalhes técnicos da comunicação entre a loja e a API do PagBank, serão completamente removidos do banco de dados da sua loja.

Este recurso serve para evitar a perda de dados ao desinstalar o módulo por acidente ou durante uma atualização da própria loja.

6. Tarefa CRON

A tarefa Cron desempenha um papel crucial, cancelando automaticamente os pedidos não pagos dentro do prazo estabelecido para Boletos Bancários e PIX, além de auxiliar no gerenciamento de estoque. Para configurá-la, entre em contato com o suporte técnico do seu provedor de hospedagem e forneça as URLs específicas geradas para a sua loja.

## 7. Estorno parcial ou total de um pedido

Para realizar o estorno, seja parcial ou total, você deve acessar a aba Pedidos e selecionar o pedido que precisa ser estornado. Depois de acessar a página do pedido desejado, role a página até localizar a opção DADOS DO PEDIDO (PAGBANK). Para realizar o estorno, você deve clicar em Estornar Transação no PagBank. Como resultado, o módulo transmitirá a requisição de estorno ao PagBank.

Após realizar o estorno, dentro de alguns segundos, o pedido receberá uma notificação para a troca de status. Pedidos com estorno total recebem o status mapeado como Cancelado, quanto que para estorno parcial recebem o status mapeado como Estornado.

Para mais informações sobre o pedido estornado, acesse a sua conta no PagBank. No menu, selecione Extratos e Relatórios → Extrato de Transações. Ao acessar a transação, role a página para localizar Extrato de movimentações da transação.

📘
Condições para realizar o estorno
Só é possível realizar o estorno se o pedido estiver em um destes status:

Aprovada

Em análise

Em disputa