# Como corrigir pagamento do WooCommerce com erro

O pagamento do WooCommerce com erro acontece quando o cliente tenta pagar mas a transação falha, é recusada ou o pedido não é confirmado mesmo após o pagamento. Quase sempre vem de chaves de API erradas (modo teste x produção), de webhook do gateway não chegando ao site ou de SSL/HTTPS mal configurado no checkout.

## O que é o pagamento do WooCommerce com erro?

No WooCommerce, o pagamento é processado por um gateway (Mercado Pago, PagSeguro, Stripe, PayPal, etc.) que troca dados com a loja por API e confirma a transação via webhook. O 'pagamento com erro' é qualquer falha nesse fluxo: a cobrança não inicia, é recusada por configuração, ou o dinheiro é debitado mas o pedido fica preso em 'Aguardando pagamento' porque a confirmação não voltou ao site.

## Como identificar

- Mensagem no checkout do tipo 'Erro ao processar o pagamento' ou 'Desculpe, houve um erro no processamento do seu pedido'.
- O cliente paga, mas o pedido fica preso no status 'Aguardando pagamento' (on-hold/pending) e nunca muda para 'Processando'.
- O gateway aparece como indisponível ou não lista a forma de pagamento na finalização.
- Nos logs (WooCommerce > Status > Logs) há entradas do gateway com 'invalid API key', 'signature mismatch' ou 'webhook 401/404'.

**Antes de começar:** Nunca exponha a chave secreta (secret key) do gateway em código público, no front-end ou em logs versionados. Faça backup e teste em staging com chaves de Sandbox antes de mexer no gateway de produção.

## Como prevenir

- Use chaves de Sandbox em staging e só troque para produção depois de validar um pedido de teste real
- Documente a URL de webhook de cada gateway e confirme que o WAF/host não bloqueia essas rotas
- Mantenha SSL válido, WooCommerce e plugins de gateway sempre atualizados e monitore os logs do gateway

Erros relacionados

- [Como corrigir checkout do WooCommerce que não funciona](https://full.services/wp-fixer/corrigir-checkout-woocommerce-nao-funciona/)
- [Como corrigir email de pedido do WooCommerce não enviado](https://full.services/wp-fixer/corrigir-email-pedido-woocommerce-nao-envia/)
- [Como corrigir Add to cart que não funciona no WooCommerce](https://full.services/wp-fixer/corrigir-add-to-cart-woocommerce/)

## Causa

- Chaves de API do gateway erradas ou em modo Sandbox/Teste enquanto a loja está em produção (ou o inverso).
- Webhook/IPN do gateway não configurado ou com URL inacessível, deixando o pedido sem confirmação automática.
- Certificado SSL ausente ou HTTPS inconsistente: o gateway recusa processar pagamento em página sem cadeado válido.
- Conflito de plugin ou cache no checkout impedindo o JavaScript do gateway (campos de cartão/redirecionamento) de carregar.
- Versão do plugin do gateway desatualizada e incompatível com a versão atual do WooCommerce ou do PHP.

## Como resolver

1. Confirme as chaves de API e o modo: no painel do gateway em WooCommerce > Configurações > Pagamentos, revise as chaves (public/secret) e garanta que o modo Teste/Sandbox está DESLIGADO em produção, usando as chaves de produção.
2. Cheque os logs do gateway: em WooCommerce > Status > Logs, selecione o log do gateway. Mensagens como 'invalid API key' ou 'signature mismatch' apontam direto para chave errada ou webhook mal configurado.
3. Configure o webhook corretamente: copie a URL de webhook/IPN exata que o plugin informa e cole no painel do provedor de pagamento. Sem isso, pedidos pagos ficam presos em 'Aguardando pagamento'.
4. Garanta SSL válido no checkout: confirme HTTPS com cadeado válido na página de checkout. Em WooCommerce > Configurações > Avançado, ative 'Forçar checkout seguro' se o gateway exigir SSL.
5. Atualize o plugin do gateway e teste: atualize o plugin do gateway, limpe o cache do checkout e faça um pedido de teste real (valor baixo) para validar todo o fluxo de ponta a ponta.

## Código

```php
// functions.php — registra no log do WooCommerce quando o webhook do gateway chega
// (ajuda a diagnosticar pedido preso em 'Aguardando pagamento')
add_action( 'woocommerce_api_request', function ( $api_request ) {
    $logger = wc_get_logger();
    $logger->info(
        'Webhook recebido para gateway: ' . sanitize_text_field( $api_request ),
        array( 'source' => 'gateway-webhook-debug' )
    );
}, 10, 1 );
// Veja em WooCommerce > Status > Logs (source: gateway-webhook-debug).
// Se NADA for registrado quando o cliente paga, o webhook nao esta chegando ao site.
```

## Perguntas frequentes

### O cliente pagou mas o pedido ficou em 'Aguardando pagamento'. Por quê?

Porque a confirmação (webhook/IPN) do gateway não chegou ao site. O dinheiro foi cobrado no provedor, mas o WooCommerce não recebeu o aviso para mudar o status. Verifique a URL de webhook no painel do gateway e se o WAF não está bloqueando essa rota.

### Onde vejo o motivo do erro de pagamento?

Em WooCommerce > Status > Logs, selecione o log do seu gateway. Mensagens como 'invalid API key', 'signature mismatch' ou 'webhook 401/404' indicam exatamente se o problema é chave, assinatura ou webhook.

### Por que o gateway não aparece no checkout?

Geralmente faltam credenciais, o método está desativado, ou o gateway exige SSL e o checkout não está em HTTPS válido. Revise as configurações do método em WooCommerce > Pagamentos e confirme o cadeado na página.

### Estou em modo de teste sem querer. Como saber?

No painel do gateway, procure a opção Modo Teste/Sandbox: se estiver marcada em produção, nenhuma cobrança real é processada. Desative o modo teste e troque para as chaves de produção do provedor.

### SSL é obrigatório para receber pagamento no WooCommerce?

Sim, na prática. A maioria dos gateways recusa processar pagamento em páginas sem HTTPS válido, e os navegadores alertam o cliente. Instale um certificado SSL e force o checkout seguro nas configurações do WooCommerce.

### Atualizei o WooCommerce e os pagamentos pararam. O que fazer?

O plugin do gateway pode estar incompatível com a nova versão. Atualize o plugin do gateway, cheque os logs por erros de compatibilidade e, se preciso, faça um pedido de teste em staging antes de confirmar na loja ao vivo.

**Fonte:** [WooCommerce — Setting up Payments](https://woocommerce.com/document/premium-payment-gateways/)