Contexto

Ao utilizar a rota:

POST 

/v3/pix/qrCodes/pay

em ambiente sandbox, pode ocorrer um erro 404 Not Found ao tentar pagar um QR Code Pix gerado a partir de uma cobrança criada via interface, sem que haja uma chave Pix cadastrada na conta.

Esse erro acontece porque, no ambiente de testes, o payload do QR Code Pix não é registrado quando a conta não possui chave Pix válida — ou quando a cobrança foi criada com a integração Pix do Bradesco (que não gera o payload no sandbox).

Observação importante

Embora tecnicamente o erro 404 esteja correto (o payload realmente não existe no sandbox), entendemos que isso pode gerar confusão para quem está integrando com a API, já que:

• A rota usada é válida;
• O payload foi extraído corretamente da cobrança;
• A expectativa do cliente é que o QR Code funcione para testes.

Exemplo de cenário que gera o erro

O fluxo abaixo costuma resultar no erro 404 Not Found em Sandbox:

Conta sem chave Pix
        ↓
Criar cobrança via interface
        ↓
Gerar QR Code Pix
        ↓
Copiar payload
        ↓
Enviar para /v3/pix/qrCodes/pay
        ↓
Erro 404

Exemplo de requisição:

{
  "qrCode": {
    "payload": "payloadObtidoDaCobranca"
  },
  "value": 50
}

Nesse cenário, o erro ocorre porque o payload do QR Code não foi registrado no ambiente Sandbox.

Conteúdos relacionados

• Criar QR Code estático.
• Pagar um QR Code.
• Configurar sua conta no Sandbox.
• O que pode ser testado em Sandbox.
• Testar pagamento de QR Code Pix.
• Como adicionar saldo em uma conta Sandbox.

Como evitar o erro

Para garantir que o teste funcione no ambiente de homologação (sandbox), é necessário cadastrar uma chave Pix na conta e gerar uma nova cobrança com QR Code associado a essa chave.

Veja a chamada para realizar um pagamento de QRCode aqui.

Fluxo recomendado para homologação

Para evitar esse comportamento:

1. Cadastre uma chave Pix na conta Sandbox.
2. Gere uma nova cobrança Pix após o cadastro da chave.
3. Obtenha o payload do QR Code gerado.
4. Execute novamente o pagamento utilizando o endpoint.
5. Valide a criação da cobrança Pix e o processamento do pagamento.

Fluxo simplificado:

Cadastrar chave Pix
        ↓
Criar cobrança Pix
        ↓
Obter payload
        ↓
Pagar QR Code
        ↓
Processar pagamento

Conteúdos relacionados

• Criar QR Code estático.
• Pagar um QR Code.
• Configurar sua conta no Sandbox.
• O que pode ser testado em Sandbox.
• Testar pagamento de QR Code Pix.
• Como adicionar saldo em uma conta Sandbox.