WooCommerce
Plugin pronto para lojas WordPress — Pix no checkout, pedido confirmado sozinho e reembolso pelo pedido.
O plugin Pix para WooCommerce coloca o Pix na finalização da compra da sua loja sem escrever código. Ele usa a mesma API desta documentação: cada pedido vira uma cobrança e o pedido é confirmado quando o Pix cai na conta da sua empresa.
Requisitos
- WordPress 6.4 ou mais novo, WooCommerce 8.3 ou mais novo, PHP 8.1 ou mais novo.
- Loja em reais (BRL).
- Uma chave de API da unidade (painel → Desenvolvedores → Chaves de API). Comece pela
sk_sandbox_….
Funciona no checkout clássico e no checkout em blocos, e com o armazenamento de pedidos de alto desempenho (HPOS).
Instalação
- Em Plugins → Adicionar novo → Enviar plugin, envie o arquivo
gateway-pix-woocommerce.zip(fornecido pelo suporte enquanto o plugin não está no diretório do WordPress) e ative. - Em WooCommerce → Configurações → Pagamentos → Pix, marque Ativar e cole a chave de API.
- Salve. O plugin mostra a unidade conectada (e se é sandbox ou produção) e cadastra o webhook da loja sozinho.
| Opção | O que faz |
|---|---|
| Onde o cliente paga | Página de pagamento Pix (QR Code, copia e cola e confirmação na hora — recomendado) ou na página do pedido da loja (código copia e cola e botão para a página de pagamento). |
| Validade do Pix | Minutos até a cobrança expirar (padrão 30). Expirou sem pagamento: o pedido é cancelado e o estoque volta. |
| Segredo do webhook | Só se você cadastrou o webhook à mão no painel. |
O que acontece com o pedido
| Momento | Pedido no WooCommerce |
|---|---|
| Cliente clica em "Finalizar compra" | Cobrança criada, pedido Aguardando, estoque reservado. O e-mail de pedido em espera leva o link e o código Pix. |
| Pix pago | Pedido Processando (ou Concluído, se todos os itens forem virtuais e para download), com a cobrança como transação e uma nota "Pix recebido". |
| Pix expirou ou foi cancelado | Pedido Cancelado, estoque devolvido. |
| Lojista cancela o pedido | A cobrança também é cancelada: o QR já mostrado não pode mais ser pago. |
| Reembolso pelo pedido | Devolução Pix total ou parcial ao pagador; o resultado final entra como nota. |
O plugin nunca confia só no aviso: ao receber um webhook, ele consulta a cobrança na API antes de mudar o pedido. Clique duplo em "Finalizar compra" não cria duas cobranças (a Idempotency-Key vem do pedido).
Loja sem https (ou webhook fora do ar)
O webhook só é cadastrado para endereços https:// públicos. Sem ele, a loja continua funcionando:
- a página "Pedido recebido" consulta a cobrança enquanto o cliente espera, e mostra Pagamento confirmado;
- a cada 5 minutos, uma tarefa do WordPress (WP-Cron) consulta os pedidos Pix ainda aguardando.
Em lojas com pouco acesso, o WP-Cron só roda quando alguém visita o site; configure um cron do servidor chamando
wp-cron.php se precisar de confirmação no prazo mesmo sem visitas.
Situações que pedem atenção
O plugin escreve uma nota no pedido e não decide sozinho quando:
- o cliente pagou dois QR Codes do mesmo pedido (devolva um pelo painel, em Pagamentos);
- o Pix caiu depois que o pedido foi cancelado (reabra o pedido ou devolva o valor);
- uma devolução foi recusada pelo banco (o reembolso registrado no pedido não saiu da conta).
Testar no sandbox
Com a chave sk_sandbox_…, faça um pedido na sua loja e, na página de pagamento, use Simular pagamento. Veja
também o sandbox.