VibeFox PagSeguro for WooCommerce — Ajuda

Requisitos

WordPress: 6.0 ou superior.

WooCommerce: 8.0 ou superior, instalado e ativo. O plugin não é ativado sem ele.

PHP: 8.0 ou superior.

Moeda: real brasileiro (BRL). O método de pagamento fica oculto na finalização de compra quando a moeda da loja (ou, na página Pay for order, a moeda do pedido) não é BRL.

HTTPS: seu site precisa ser acessível pela internet por HTTPS para que o PagBank possa enviar as notificações de pagamento.

Conta no 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 de sandbox no portal de desenvolvedores do PagBank e copie o token dela. Os tokens de sandbox e de produção funcionam apenas no seu próprio ambiente.

Chave de licença VibeFox: comprada em vibefox.net. Uma chave funciona para um domínio.

Instalação

1. No WordPress, vá em Plugins > Add New > Upload Plugin, escolha o arquivo ZIP do plugin e clique em Install Now. Você também pode enviar a pasta wcp_pagseguro_gateway para /wp-content/plugins/ por FTP.

2. Clique em Activate.

3. Abra as configurações: WooCommerce > Settings > Payments > PagSeguro / PagBank > Manage, ou clique em Settings abaixo do nome do plugin na página Plugins.

4. Insira sua chave de licença VibeFox no bloco de licença no topo da página e clique em Activate.

5. Insira o token de sandbox e, para receber pagamentos reais, o token de produção.

6. Ative Enable / Disable e salve. Faça pagamentos de teste com Sandbox Mode ativado e depois desative-o para receber pagamentos reais.

Configuração

Todas as configurações estão em uma única página: WooCommerce > Settings > Payments > PagSeguro / PagBank. Abaixo do título, 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 na finalização de compra) e quando a moeda da loja não é BRL. Na lista de métodos de pagamento, o PagBank aparece como pendente de configuração até que o token do modo atual seja informado, e um selo de modo de teste aparece enquanto o modo sandbox estiver ativado.

Geral

Enable / Disable: Enable PagSeguro/PagBank payments 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 de compra. Padrão: PagSeguro / PagBank.

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

Conta no PagBank

Esta 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). Os novos pagamentos vão para o sandbox do PagBank com o token de sandbox, e um aviso SANDBOX MODE aparece na finalização de compra. As consultas de status e os reembolsos de um pedido sempre usam o ambiente e o token em que o pagamento dele foi criado. Padrão: ativado.

Sandbox token: o token de sandbox do PagBank. É usado enquanto o modo sandbox estiver ativado.

Production token: o token de produção do PagBank. É usado quando o modo sandbox está desativado. Mantenha-o em sigilo.

O token único da versão 1.0 é movido automaticamente: se o modo sandbox estava ativado, ele se torna o token de sandbox; caso contrário, continua como token de produção.

Notificações de pagamento

Cada pagamento informa ao PagBank para onde enviar as mudanças de status, por isso não há nada para configurar no PagBank. A seção mostra a URL de notificação. Ela tem este formato: https://your-site/wc-api/webhook_wc_pagseguro/. O endereço precisa ser acessível pela internet por HTTPS.

As notificações que trazem o cabeçalho x-authenticity-token são verificadas com o token do ambiente do pedido; uma assinatura inválida é rejeitada. O conteúdo da própria notificação nunca é considerado confiável: o plugin sempre lê o checkout e o pedido no PagBank pela API do PagBank (status, valor e moeda) antes de alterar o pedido.

Avançado

Debug log: Log API requests and notifications grava os detalhes em WooCommerce > Status > Logs, origem wcp_pagseguro_gateway. Erros são sempre registrados. Os logs não contêm tokens nem dados de clientes. Padrão: desativado.

Delete Data on Uninstall: Remove the gateway settings and logs when the plugin is deleted. Padrão: desativado.

Finalização de compra

O cliente escolhe o método de pagamento (por padrão PagSeguro / PagBank) e faz o pedido. O plugin cria um checkout no PagBank pelo valor total exato do pedido em BRL, como um único item, Order # com o número do pedido 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 dos campos do plugin Brazilian Market on WooCommerce e um telefone brasileiro são preenchidos quando a loja os tem; o cliente pode completá-los ou corrigi-los 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 5 minutos antes de o temporizador Hold stock do WooCommerce cancelar o pedido não pago (no mínimo 10 minutos), ou após 120 minutos quando o estoque não é reservado.

Depois de pagar, o cliente volta para a loja. Esse retorno é verificado da mesma forma que uma notificação: o plugin lê o pagamento pela API do PagBank, e um retorno sozinho nunca marca um pedido como pago. Um pedido pago, ou um pagamento que está aguardando (boleto, PIX, análise), leva à página de pedido recebido; o pedido é confirmado pela notificação se o PagBank ainda não a tiver enviado.

Se o pagamento não foi concluído, o cliente volta para a página Pay for order 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. Se o pagamento foi cancelado e o pedido junto, o cliente vai para o carrinho com The PagBank payment was cancelled, so the order was cancelled.

Quando o cliente paga novamente, o checkout aberto no PagBank é reaproveitado se o valor e o ambiente forem os mesmos e ele não expirar em menos de 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 pedido.

Se o PagBank não conseguir iniciar o pagamento, o cliente vê 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 informado pelo PagBank é adicionado às notas do pedido.

O método de pagamento funciona na finalização de compra clássica, no bloco de Finalização de compra e na página Pay for order. É compatível com o HPOS (armazenamento de pedidos de alto desempenho) do WooCommerce.

O plugin não tem formulário de cartão no site, cartões salvos, assinaturas ou cobranças recorrentes, nem pagamentos divididos ou marketplaces. Os métodos de pagamento e os parcelamentos são os configurados na sua conta do PagBank.

Pedidos e reembolsos

Status do pedido

Pending payment: o cliente foi enviado ao PagBank e ainda não pagou. Uma nota mostra o ID do checkout no PagBank e o ambiente. Se a página de pagamento expirar sem pagamento, uma nota informa isso e o status não muda.

Processing: o pagamento foi confirmado. Este é o status padrão do WooCommerce após o pagamento; pedidos que contêm apenas produtos virtuais para download passam para Concluído. A nota do pedido mostra o valor, o método de pagamento e o ID da cobrança no PagBank, que também é o ID da transação do pedido.

On hold: um boleto ou PIX foi gerado e aguarda pagamento; o pagamento está em análise; um pagamento com cartão foi autorizado, mas não capturado (capture-o no PagBank); o valor ou a moeda pagos não correspondem ao pedido; ou um pagamento chegou depois que o WooCommerce cancelou o pedido não pago (verifique o estoque e depois conclua o pedido ou reembolse o pagamento no PagBank). A nota do pedido explica o caso.

Failed: o pagamento foi recusado. O cliente pode pagar novamente pela página Pay for order.

Cancelled: o pagamento foi cancelado, por exemplo um boleto ou PIX vencido.

Refunded: o pagamento foi totalmente reembolsado no painel do PagBank.

Cada status do PagBank é aplicado apenas uma vez, então notificações ou retornos repetidos não acrescentam notas, e-mails nem baixas de estoque. Se chegar um segundo pagamento para um pedido que já está pago, uma nota pede que você o reembolse no PagBank.

Reembolsos

Abra o pedido, clique em Refund, informe o valor e clique em Refund via PagSeguro / PagBank (o botão mostra o título do seu método de pagamento). São aceitos reembolsos totais e parciais. 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 WooCommerce 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 às notas do pedido com o ID da cobrança.

Reembolsos feitos no painel do PagBank não são importados como linhas de reembolso do WooCommerce. Um reembolso total coloca o pedido como Reembolsado; um reembolso parcial adiciona uma nota com o valor reembolsado, e você pode lançar o reembolso no pedido manualmente.

Chave de licença

O plugin funciona com uma chave de licença VibeFox obtida em vibefox.net. O bloco de licença fica no topo de WooCommerce > Settings > Payments > PagSeguro / PagBank. Cole a chave em License key e clique em Activate. O bloco mostra o status, por exemplo a data até a qual a licença está ativa, e o seu domínio. Use Check now para verificar o status novamente, Change key para informar outra chave e Remove key para removê-la deste site. O link Manage licenses and domains in your account abre sua conta em vibefox.net.

Uma chave funciona para um domínio. Remover a chave de um site não libera a vaga de domínio; libere-a na sua conta em vibefox.net.

Sem uma chave ativa, o PagBank não é exibido aos clientes na finalização de compra. Se um pagamento for iniciado mesmo assim, o cliente vê This payment method is not available. Please choose another one. Os gerentes da loja que estiverem logados continuam vendo o método de pagamento, marcado como (unlicensed — visible to admins only), para que você possa configurar e testar o plugin antes de comprar uma chave. Um lembrete aparece na página Plugins e nas páginas do WooCommerce. Os pedidos existentes não são afetados: pagamentos já iniciados continuam sendo confirmados e os reembolsos funcionam.

Quando uma licença expira, o plugin continua funcionando, mas atualizações e suporte exigem renovação. O status é verificado de novo automaticamente em segundo plano.

Solução de problemas

O PagBank não aparece na finalização de compra: confira 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 da loja é BRL. A página de configurações mostra um aviso em cada um desses casos.

O pagamento foi feito, mas o pedido continua em Aguardando pagamento: o PagBank ainda não informou o pagamento e o cliente não voltou para a loja. O pedido é atualizado assim que a notificação chegar. Verifique se o seu site está acessível pela internet por HTTPS e consulte WooCommerce > Status > Logs, origem wcp_pagseguro_gateway.

A notificação responde Invalid signature: o x-authenticity-token não corresponde ao token do ambiente em que o pedido foi pago. Confira 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 pedido está faltando, ou o pedido estava sendo atualizado por outra requisição no mesmo momento. O PagBank tenta a notificação novamente.

A notificação responde Order not found: o pedido não existe nesta loja ou foi pago com outro método de pagamento. Nada é alterado.

O cliente vê This order is already being processed: uma notificação ou o retorno do cliente estava atualizando o pedido ao mesmo tempo. O cliente pode tentar de novo em instantes.

O cliente vê PagBank payments are temporarily unavailable: o token do modo atual está faltando ou foi recusado pelo PagBank.

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

O pedido está On hold com a nota Amount/currency does not match: o PagBank informou um pagamento cujo valor ou moeda difere do total do pedido, por exemplo porque o pedido foi editado depois que a página de pagamento foi criada. Compare os valores no PagBank e conclua ou reembolse o pedido manualmente.

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 recusado. Informe o token correto e tente novamente.

O bloco de licença mostra um erro: siga a mensagem exibida no bloco. Por exemplo, se a chave já estiver em uso em outro domínio, libere uma vaga na sua conta em vibefox.net e clique em Check now. Se o endereço do site mudou, clique em Check now para ativar a chave no novo domínio. Se o servidor de licenças não puder ser acessado, o plugin continua funcionando com o último status conhecido.

Desinstalação

Desativar o plugin mantém todos os dados. Para removê-lo, desative-o e exclua-o na página Plugins. A chave de licença e o status de licença deste plugin são sempre removidos. As configurações do gateway, as demais opções do plugin e os logs só são removidos se Delete Data on Uninstall estiver ativado. Caso contrário, eles permanecem para uma reinstalação futura. Os pedidos existentes mantêm suas notas de pagamento, IDs de transação e dados do PagBank.

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