05 Dúvidas Comuns & Pré Requisitos
Posso integrar o módulo com a Clear Sale?
Sim, você pode usar serviços externos como a Clear Sale para analisar suas transações.
Como configurar o uso com esses serviços?
O primeiro passo é definir em nosso módulo o comportamento de apenas "Autorizar" o pedido e não a "Autorização e Captura" como é definido por padrão.
Para isso acesse:
Lojas → Vendas → Formas de Pagamento → PagBank → Cartão de Crédito
Desmarque a opção destacada:
E defina com "Autorizar", salve.
Como automatizar o fluxo de captura e negação?
Se você quer utilizar a resposta da Clear Sale para definir entre capturar ou negar o pagamento, você irá precisar de um módulo adcional.
Esse módulo é gratuito e faça essa ação:
https://github.com/elisei/pagbank-and-clearsales
O módulo oferece recorrência?
Não, no entanto como padrão de desenvolvimento você pode estender o nosso módulo para aplicar a Flag de Recorrência que possibilita o fluxo de cobranças recorrentes.
Como implementar a recorrência?
Um bom ponto de partida por ser o módulo PagBank Flag Recurring Magento.
Esse é um módulo gratuito que insere o recurso de recorrência aos pagamentos feitos.
Como realizar testes com cartão?
⚠️ Atenção: Você só pode realizar testes no ambiente sandbox.
Para a realização dos testes, você deve usar as seguintes bandeiras:
| Bandeira | Número do Cartão | Tipo de Teste | Resultado do Teste | CVV | Expiração |
|---|---|---|---|---|---|
 |
4539620659922097 | Autorizado | ✔️ Pagamento Aceito | 123 | 12/32 |
|
4929291898380766 | Negado | 🚫 Informação de Negação no Checkout | 123 | 12/32 |
 |
5240082975622454 | Autorizado | ✔️ Pagamento Aceito | 123 | 12/32 |
|
5530062640663264 | Transação Não Autorizada | 🚫 Informação de Negação no Checkout | 123 | 12/32 |
 |
345817690311361 | Autorizado | ✔️ Pagamento Aceito | 1234 | 12/32 |
|
372938001199778 | Transação Não Autorizada | 🚫 Informação de Negação no Checkout | 1234 | 12/32 |
 |
4514161122113757 | Autorizado | ✔️ Pagamento Aceito | 123 | 12/32 |
|
4389350446134811 | Transação Não Autorizada | 🚫 Informação de Negação no Checkout | 123 | 12/32 |
 |
6062828598919021 | Autorizado | ✔️ Pagamento Aceito | 123 | 12/32 |
|
6062822916014409 | Transação Não Autorizada | 🚫 Informação de Negação no Checkout | 123 | 12/32 |
Qr Code do Pix não reconhecido?
Isso ocorre porque sua conta ainda não tem um chave Pix cadastrada. Você precisa criar uma chave PIX em sua conta PagBank e aguardar até 24 horas para habilitar o serviço.
Como oferecer parcelamento sem juros?
Acesse a configuração de Formas de Pagamentos -> Configuração do PagBank -> Cartão de Crédito -> Parcelamento e Juros
- Desmarque a caixa "Utilizar o valor do sistema"
- Escolha o número de parcelas que deseja oferecer sem juros
- Clique em "Gravar Configuração"
⚠️ Atenção: Após gravar a configuração, o Magento pode solicitar a limpeza do cache.
Como definir um limite para o parcelamento?
Acesse a configuração de Formas de Pagamentos -> Configuração do PagBank -> Cartão de Crédito -> Parcelamento e Juros
- Desmarque a caixa "Utilizar o valor do sistema"
- Escolha o número máximo de parcelas
- Clique em "Gravar Configuração"
⚠️ Atenção: Após gravar a configuração, o Magento pode solicitar a limpeza do cache.
Como ocorre o cancelamento de pedidos por boleto?
Implementamos um cron que roda de segunda à sexta às 7 da manhã:
Link para o arquivo crontab.xml
Esse cron busca pedidos definidos com estado "new" ou "payment_review":
Link para o arquivo GetStatusUpdate.php
E realiza uma consulta na Pags para verificar o status:
Link para o arquivo Update.php
Caso o pedido ainda não esteja definido como "Pago", ele é cancelado:
Link para o arquivo Update.php
Portanto, é importante observar se:
- O pedido feito via boleto está com o estado esperado "new".
- O período para o cancelamento passou do vencimento do boleto por mais de 2 dias.
Como ocorre o cancelamento de pedidos por pix?
Implementamos um cron que roda todo dia a cada 5 minutos:
Link para o arquivo crontab.xml
Esse cron busca pedidos definidos com estado "new" ou "payment_review":
Link para o arquivo GetStatusUpdate.php
E realiza uma consulta na Pags para verificar o status:
Link para o arquivo Update.php
Caso o pedido ainda não esteja definido como "Pago", ele é cancelado:
Link para o arquivo Update.php
Portanto, é importante observar se:
- O pedido feito via boleto está com o estado esperado "new".
- O período para o cancelamento passou do vencimento do PIX por mais de 5 minutos.
Como ocorre o cancelamento de pedidos por cartão?
Esse processo é automático, no entanto caso a entrega de status (webhook) falhe há um fluxo via cron para atualizar o pedido.
Nesse processo realizamos a consulta de todos os pedidos de cartão que estejam pendentes as 8 da manhã:
Link para o arquivo crontab.xml
Esse cron busca pedidos definidos com estado "new" ou "payment_review":
Link para o arquivo GetStatusUpdate.php
E realiza uma consulta na Pags para verificar o status para sincronizar o pedido em sua loja:
Onde é capturado o CPF/CNPJ?
Consulte seu desenvolvedor para compreender onde esse atributo é salvo, após isso faça o relacionamento em
Acesse a configuração de Formas de Pagamentos -> Configuração do PagBank -> Desenvolvedores -> Configuração de Relacionamento de Atributo
- Desmarque a caixa "O CPF/CNPJ será um atributo obtido do"
- Escolha o perfil da sua loja
- Clique em "Gravar Configuração"
⚠️ Atenção: Se durante o processo de compra o valor por você informado não for identificado ou validado haverá a solicitação ao consumidor para informar o CPF/CNPJ no formulário de pagamento. :warning: Atenção: Após gravar a configuração, o Magento pode solicitar a limpeza do cache.
Como desativar o campo CPF/CNPJ no formulário de pagamento?
Essa definição é feita em cada método de pagamento, no entanto ela só será respeitada quando conseguimos capturar o CPF/CNPJ no campo indicado por você na configuração.
Para definir onde esse valor será capturado siga o processo abaixo.
Acesse a configuração de Formas de Pagamentos -> Configuração do PagBank -> Desenvolvedores -> Configuração de Relacionamento de Atributo
- Desmarque a caixa "O CPF/CNPJ será um atributo obtido do"
- Escolha o perfil da sua loja
- Clique em "Gravar Configuração"
⚠️ Atenção: Após gravar a configuração, o Magento pode solicitar a limpeza do cache.
Onde ativar o log?
Acesse a configuração de Formas de Pagamentos -> Configuração do PagBank -> Desenvolvedores
- Desmarque a caixa "Utilizar o valor do sistema" do campo Deburar
- Selecione "Sim"
- Clique em "Gravar Configuração"
⚠️ Atenção: Após gravar a configuração, o Magento pode solicitar a limpeza do cache.
Onde fica o log?
O log são gerados no nivel servidor, ele é gerado na pasta var/log no arquivo payment.log
Como ler o log?
Essa é a estrutura de um log:
[2023-04-27T18:10:07.755814+00:00] main.DEBUG: array (
'url' => 'https://sandbox.api.pagseguro.com/orders',
'header' => '****',
'payload' => '{"metadata":[{"store_id":1}],"reference_id":"000000260","description":"Pagamento do pedido #000000260","amount":{"value":5263,"currency":"BRL"},"customer":{"name":"Bruno Elisei","email":"*** protected ***","tax_id":"*** protected ***","phones":[{"country":55,"area":34,"number":"*** protected ***","type":"MOBILE"}],"address":{"postal_code":"38017190","street":"Rua Doutor Jesu\\u00edno Felic\\u00edssimo","number":"*** protected ***","locality":"Rua Doutor Jesu\\u00edno Felic\\u00edssimo","complement":"Boa Vista","city":"Uberaba","region":"Minas Gerais","region_code":"MG","country":"BRA"}},"items":[{"reference_id":"24-WB04","name":"Push It Messenger Bag","quantity":1,"unit_amount":4500}],"shipping":{"address":{"postal_code":"38017190","street":"Rua Doutor Jesu\\u00edno Felic\\u00edssimo","number":"*** protected ***","locality":"Rua Doutor Jesu\\u00edno Felic\\u00edssimo","complement":"Boa Vista","city":"Uberaba","region":"Minas Gerais","region_code":"MG","country":"BRA"}},"notification_urls":["https:\\/\\/v246-pagseguro.magento.local\\/pagbank\\/notification\\/all\\/"],"charges":[{"amount":{"value":5263,"currency":"BRL"},"payment_method":{"type":"CREDIT_CARD","soft_descriptor":"DemoLocal","capture":true,"installments":"2","card":{"id":"CARD_E3B71BE4-2D08-40E1-8C46-B87F6B3FCDEA","store":false}},"recurring":{"type":"INITIAL"}}]}',
'response' => '{"id":"ORDE_4954A463-CEF4-4EED-A899-25DCEDF04B6F","reference_id":"000000260","created_at":"2023-04-27T15:10:05.318-03:00","customer":{"name":"Bruno Elisei","email":"*** protected ***","tax_id":"*** protected ***","phones":[{"type":"MOBILE","country":"55","area":"34","number":"*** protected ***"}]},"items":[{"reference_id":"24-WB04","name":"Push It Messenger Bag","quantity":1,"unit_amount":4500}],"shipping":{"address":{"street":"Rua Doutor Jesu\\u00edno Felic\\u00edssimo","number":"*** protected ***","complement":"Boa Vista","locality":"Rua Doutor Jesu\\u00edno Felic\\u00edssimo","city":"Uberaba","region_code":"MG","country":"BRA","postal_code":"38017190"}},"charges":[{"id":"CHAR_D18FE3B8-10CA-4C59-AD35-6582BD8193B9","status":"PAID","created_at":"2023-04-27T15:10:05.826-03:00","paid_at":"2023-04-27T15:10:06.000-03:00","description":"","amount":{"value":5263,"currency":"BRL","summary":{"total":5263,"paid":5263,"refunded":0}},"payment_response":{"code":"20000","message":"SUCESSO","reference":"032416400102"},"payment_method":{"type":"CREDIT_CARD","installments":2,"capture":true,"card":{"id":"CARD_E3B71BE4-2D08-40E1-8C46-B87F6B3FCDEA","brand":"visa","first_digits":"453962","last_digits":"2097","exp_month":"6","exp_year":"2026","holder":{"name":"Apro"},"store":false},"soft_descriptor":"DemoLocal"},"recurring":{"type":"INITIAL"},"links":[{"rel":"SELF","href":"https:\\/\\/sandbox.api.pagseguro.com\\/charges\\/CHAR_D18FE3B8-10CA-4C59-AD35-6582BD8193B9","media":"application\\/json","type":"GET"},{"rel":"CHARGE.CANCEL","href":"https:\\/\\/sandbox.api.pagseguro.com\\/charges\\/CHAR_D18FE3B8-10CA-4C59-AD35-6582BD8193B9\\/cancel","media":"application\\/json","type":"POST"}]}],"notification_urls":["https:\\/\\/v246-pagseguro.magento.local\\/pagbank\\/notification\\/all\\/"],"links":[{"rel":"SELF","href":"https:\\/\\/sandbox.api.pagseguro.com\\/orders\\/ORDE_4954A463-CEF4-4EED-A899-25DCEDF04B6F","media":"application\\/json","type":"GET"},{"rel":"PAY","href":"https:\\/\\/sandbox.api.pagseguro.com\\/orders\\/ORDE_4954A463-CEF4-4EED-A899-25DCEDF04B6F\\/pay","media":"application\\/json","type":"POST"}]}',
'error_msg' => NULL,
) [] []Nessa estrutura você irá ver os valores para:
Indica o endpoint da API que estamos consumindo.
São as informações passadas para a conexão com API. Esse valor é protegido e não será visível.
Aqui é a informação estamos encaminhando ao PagBank. Alguns valores podem estar protegidos.
É a informação retornada pelo PagBank para o nosso processo.
Destaca o erro obtido no processo, é a exception da Magento. No response é que deverá ler o erro reportado pela PagBank
Transações com Cartão de Crédito
No PagBank, o cliente só atinge a página de sucesso se a transação com o cartão de crédito for aprovada pelo banco. Sendo assim, são esperados três estados possíveis:
- "new": Quando o serviço de notificação (Callback/Webhook) ainda não notificou a aplicação.
- "payment_review": Estado opcional definido quando a loja utiliza o comportamento de apenas "Autorizar" o pagamento.
- "processing": Estado final de atuação do PagBank sobre esse pedido.
Portanto, se a sua loja opera no perfil de Ação de Pagamento no modo "Autorizar", na página de sucesso o pedido pode aparecer como:
- "new" ou "payment_review": Em ambos os casos, essa é uma transação de sucesso onde o banco já autorizou o pagamento. Apenas a sua decisão interna pode negar esse pedido no futuro.
Já se o perfil for "Autorizar e Capturar", na página de sucesso os estados podem ser:
- "new" ou "processing": Em ambos os casos, essa também é uma transação de sucesso.
graph TD
A{Checkout}
A --> B{Pagamento com Cartão de Crédito}
B --> C(Autorizado)
B --> E(Negado/Canceled)
E --> |Tela de Checkout|F[Informa o motivo da negação]
C --> G{Ação de Pagamento}
G --> H[Autorizar]
G --> I[Autorizar e Capturar]
H --> J{Serviço de Notificação}
J --> K[Notificação Recebida?]
K --> |Não|L(State New)
K --> |Sim|M[Processamento Interno]
M --> N(State Payment Review)
I --> O{Serviço de Notificação}
O --> P[Notificação Recebida?]
P --> |Não|Q(State New)
P --> |Sim|R(State Processing)
Transações com Métodos Externos (Pix, Boleto, Pagar com PagBank)
Apenas transações geradas com sucesso são encaminhadas para a página de sucesso, e o estado pode ser:
- "new": Quando o serviço de notificação (Callback/Webhook) ainda não notificou a aplicação.
- "payment_review": Quando a notificação foi recebida e já processada, indicando que aguarda a conclusão do pagamento pelo consumidor.
graph TD
A{Checkout}
A --> S{Pagamento com Métodos Externos}
S --> T(Gerado com Sucesso)
S --> U(Falha)
U --> |Tela de Checkout|V[Informa o motivo da falha]
T --> W{Serviço de Notificação}
W --> X[Notificação Recebida?]
X --> |Não|Y(State New)
X --> |Sim|Z(State Payment Review)
Este módulo possui versões específicas para Adobe ou Magento, que atualmente são suportadas:
- Versões 2.4.6
- Versões 2.4.0 até 2.4.5
- Versões 2.3.x
Recomendamos também a leitura do ciclo de suporte.
Por favor, consulte a seção de instalação para escolher a versão adequada.