Virtuaria PagBank / PagSeguro para Woocommerce

FAQ

1 – Qual é a licença do plugin?

Este plugin está licenciado como GPLv3. O código é 100% aberto (Open Source). Não disponibilizamos versões PRO com funcionalidades extras.

2 – O que eu preciso para utilizar este plugin?

• Ter instalado uma versão atual do plugin WooCommerce.

• Ter instalado uma versão atual do plugin WooCommerce Extra Checkout Fields for Brazil.

• Possuir uma conta no PagSeguro.

• Caso deseje utilizar pagamentos com Pix, é preciso cadastrar uma chave aleatória em seu painel de vendedor no PagSeguro.

3 – PagSeguro recebe pagamentos de quais países?

No momento o PagSeguro recebe pagamentos apenas do Brasil e utilizando o real como moeda.
Configuramos o plugin para receber pagamentos apenas de usuários que selecionaram o Brasil nas informações de pagamento durante o checkout.

4 – Quais são os meios de pagamento que o plugin aceita?

São aceitos pagamentos com cartão de crédito, pix e boleto bancário, entretanto você precisa ativá-los na sua conta.
Confira os meios de pagamento e parcelamento.

5 – Como que o plugin faz integração com PagSeguro?

Fazemos a integração baseada na documentação oficial do PagSeguro que pode ser encontrada nos “guias de integração” utilizando a última versão da API de pagamentos.

6 – É possível enviar os dados de “Número”, “Bairro” e “CPF” para o PagSeguro?

Sim é possível, basta utilizar o plugin “WooCommerce Extra Checkout Fields for Brazil“.

7 – O pedido foi pago e ficou com o status de “processando” e não como “concluído”, isto está certo?

Sim, por padrão em compras pagas o status do pedido muda automaticamente para processando, significa que pode enviar sua encomenda. Porém, definir o status como “concluído” é atribuição do lojista ao final do processo de venda e entrega.

Para produtos baixáveis a configuração padrão do WooCommerce é permitir o acesso apenas quando o pedido tem o status “Concluído”, entretanto nas configurações do WooCommerce na aba Produtos é possível ativar a opção “Conceder acesso para download do produto após o pagamento” e assim liberar o download quando o status do pedido está como “processando”.

Se os dados estão corretos, você deve acessar a página “WooCommerce > Status do Sistema” e verificar se fsockopen e cURL estão ativos. É necessário procurar ajuda do seu provedor de hospedagem caso você tenha o fsockopen e/ou o cURL desativados.

Por último é possível ativar a opção de Log de depuração nas configurações do plugin e tentar novamente fechar um pedido (você deve tentar fechar um pedido para que o log grave o erro). Com o log é possível saber exatamente o que está dando errado com a sua instalação.

Caso você não entenda o conteúdo do log não tem problema, você pode me abrir um “tópico no fórum do plugin” com o link do log (utilize o pastebin.com.

8 – Tem confirmação automática dos pagamentos? O status do pedido é alterado automaticamente?

Sim, o status é alterado automaticamente usando a API de notificações de mudança de status do PagSeguro.

9 – Situações comuns para bloqueio no recebimento de notificações do PagSeguro pelo plugin

O motivo mais comum é algum plugin de segurança, firewall ou ferramenta no servidor onde a loja está rodando estar bloqueando as notificações. Neste caso, basta desativar o bloqueio ou incluir uma exceção para não barrar as notificações que tem o PagSeguro como origem.

Exemplos:

• Site com CloudFlare, pois por padrão serão bloqueadas quaisquer comunicações de outros servidores com o seu. É possível resolver isso desbloqueando a lista de IPs do PagSeguro.

• Plugin de segurança como o “iThemes Security” com a opção para adicionar a lista do HackRepair.com no .htaccess do site. Acontece que o user-agent do PagSeguro está no meio da lista e vai bloquear qualquer comunicação. Você pode remover isso da lista, basta encontrar onde bloquea o user-agent “jakarta” e deletar ou criar uma regra para aceitar os IPs do PagSeguro).

• mod_security habilitado, neste caso vai acontecer igual com o CloudFlare bloqueando qualquer comunicação de outros servidores com o seu. Como solução você pode desativar ou permitir os IPs do PagSeguro.

10 – Funciona com o Sandbox do PagSeguro?

Sim, funciona e basta você ativar isso nas opções do plugin, além de configurar o seu “e-mail de testes“

Lembrando que, se estiver fazendo testes na Sandbox, é comum ocorrerem instabilidades e isto pode fazer com que o PagSeguro não envie até o plugin as atualizações de status.

11 – Quais URLs eu devo usar para configurar “Notificação de transação” e “Página de redirecionamento”?

Não é necessário configurar qualquer URL para “Notificação de transação” ou para “Página de redirecionamento”, o plugin já diz para o PagSeguro quais URLs serão utilizadas.

12 – Dificuldades ao usar a Sandbox

Em conversa com a equipe de integração do PagSeguro, nos foi informado que a API Orders não é 100% atualizada com a Sandbox. Portanto, é possível que algum dos problemas abaixo aconteça:

• Transação não aparece no painel sandbox apesar de retorno da API correto;
• Notificações de mudança de status não chegam à loja;
• Falha ao reembolsar;
• Dificuldades ao fazer login no painel da sandbox;
• Internal Server Error;
• Transaction is not found;
• Operation timed out;
• Bad Gateway;
• External service error.

13 – Quais valores meus clientes podem pagar com este plugin?

Não há valores máximos para as vendas, porém existem valores mínimo a serem transacionados com o pagseguro, segue lista:

Método | Bandeira | Valor Mínimo (R$) | Parcela Mínima (R$)
Crédito | Visa | 1,00 | 5,00
Crédito | Mastercard | 0,20 | 5,00
Crédito | American Express | 0,20 | 5,00
Crédito | Demais bandeiras | 0,20 | 5,00
Boleto | – | 0,20 | –
Pix | – | 1,00 | –

14 – Este plugin permite o reembolso total e parcial da venda?

Sim, você pode reembolsar pedidos com status processando indo direto a página do pedido no woocommerce e clicar em Reembolso -> Reembolso via Pagseguro e setar o valor seja ele total ou parcial.

15 – Tem valor mínimo para reembolso?

Sim, o valor mínimo para reembolso via loja virtual é R$ 1,00.

16 – Onde encontro o log do plugin ?

No menu “Woocommerce > Status > Logs”.

Também é possível gerar um relatório detalhado do sistema no menu “Woocommerce > Status”, através do botão “Obter Relatório do Sistema”.

17 – Qual o formato correto do campo “Nome na Fatura” do cartão?

O PagSeguro não permite que o campo “Nome na Fatura” possua mais de 17 caracteres. Também não permite o uso de caracteres especiais ou espaços em branco. Isso pode gerar a mensagem “PagSeguro: Verifique os dados digitados e tente novamente”. A partir da versão 2.3.0, a configuração do plugin não permite que o limite de caracteres seja excedido, então, caso tenha preenchido este campo em uma versão antiga e o nome esteja fora do padrão, basta ajustar o campo e salvar a configuração.

18 – Pedidos no Pix sendo Cancelado

Quando uma compra é feita via pagamento com Pix, é criado um pedido com status “Aguardando” no painel, porém, caso o pagamento do Pix não seja identificado até o tempo limite, o pedido mudará para o status “Cancelado” automaticamente. O tempo limite é definido no campo “Validade do Código PIX” na tela de configurações do plugin (existe uma tolerância de 30 min, além do tempo limite).

Se o pagamento foi feito, mas não identificado pelo plugin, algumas orientações podem ser encontradas no tópico 9 desta FAQ.

19 – Como ativar as taxas especiais?

A partir da versão 2.5.0 a Virtuaria em parceria com o PagSeguro, disponibilizam condições especiais relacionadas a taxa cobrada dos lojistas usuários do plugin. Para habilitar estas novas taxas é necessário desconectar o plugin e reconectá-lo utilizando uma das taxas especiais fornecidas na tela de configuração do plugin.

Atualmente temos as seguintes opções:

• Especial Virtuaria 01: Crédito 3,79% (recebimento em 30 dias) | Pix 0,99% | Boleto R$ 2,99;
• Especial Virtuaria 02: Crédito 4,39% (recebimento em 14 dias) | Pix 0,99% | Boleto R$ 2,99;
• Negociada PagSeguro (caso tenha negociado com o PagSeguro uma taxa personalizada);
• Padrão do PagSeguro.

Observação: As taxas podem ser alteradas a critério do PagSeguro.

20 – Ao utilizar o 3DS, minha loja estará livre de disputas no PagBank?

O uso da autenticação 3DS não garante a prevenção de disputas em sua loja online. O programa de proteção ao comprador permanece ativo, exigindo que você mantenha registros de entrega em nome do titular do cartão para contestar possíveis reclamações. No entanto, quando uma transação é autenticada, o banco emissor assume a responsabilidade por chargebacks fraudulentos (Liability shift), proporcionando maior segurança. Além disso, a autenticação 3DS aumenta a taxa de aprovação, reduzindo suspeitas de compras não autorizadas. Importante notar que o 3DS aborda apenas casos de fraude, não questões relacionadas à entrega ou direitos do consumidor, como qualidade do produto/serviço.

21 = Problemas na confirmação de pagamento Pix

Sua loja virtual está configurada para receber confirmações automáticas de pagamento do PagSeguro/PagBank através do plugin Virtuaria PagSeguro, mas essas notificações estão sendo bloqueadas pelo servidor de hospedagem antes mesmo de chegarem ao seu site. Isso acontece porque:

O servidor identifica as notificações como “não seguras”
O PagSeguro envia as notificações usando um identificador técnico (Go-http-client/2.0), que alguns servidores bloqueiam automaticamente.

Firewalls de segurança estão interferindo
Muitas hospedagens usam sistemas de proteção (como ModSecurity ou CDN) que podem bloquear requisições de formatos específicos.

Como Resolver?
Passo 1: Entre em Contato com o Suporte da Sua Hospedagem
Explique que o servidor está bloqueando as notificações do PagSeguro e solicite:

Adicionar à lista de permissões (whitelist):
✅ /wc-api/WC_Virtuaria_PagSeguro_Gateway
✅ Go-http-client/2.0

Desativar bloqueios temporários:
Peça para verificarem se o firewall ou CDN está bloqueando requisições para o endpoint:

/wc-api/WC_Virtuaria_PagSeguro_Gateway

O Que Escrever para o Suporte? Use este modelo:

Assunto: Bloqueio de Notificações do PagSeguro

Olá,

Estou com problemas para receber notificações de pagamento do PagSeguro em minha loja através do plugin Virtuaria PagSeguro.

Detalhes técnicos:

Endpoint bloqueado: /wc-api/WC_Virtuaria_PagSeguro_Gateway

Código de erro no servidor: HTTP 406

utilizado: Go-http-client/2.0

Solicito que:

Adicione à whitelist do firewall

Verifiquem se o endpoint acima está liberado

Segue exemplo do log com o erro:
15.229.10.19 – – [29/Apr/2025:16:45:06 -0300] “POST /wc-api/WC_Virtuaria_PagSeguro_Gateway HTTP/2.0” 406 226 “-” “Go-http-client/2.0”

Atenciosamente,
[Seu Nome]

Importante!
Se você usa Cloudflare ou CDN:
Desative temporariamente ou configure regras para não bloquear o User-Agent Go-http-client/2.0.

O plugin Virtuaria PagSeguro está funcionando corretamente:
O problema não é do plugin, mas sim de configurações de segurança externas.