Testar pagamento de QRCodes Pix

O ambiente Sandbox permite validar o fluxo completo de pagamento de um QR Code Pix, possibilitando testar integrações relacionadas ao recebimento de pagamentos sem movimentar valores reais.

Esse cenário é especialmente útil para validar a criação de cobranças Pix, o processamento do pagamento, o recebimento de webhooks e as atualizações de status realizadas pela sua aplicação.

Quando utilizar

Utilize este fluxo quando precisar:

• homologar pagamentos via Pix;
• validar integrações com QR Code Pix;
• testar recebimentos Pix em ambiente controlado;
• validar webhooks relacionados a cobranças Pix;
• verificar o comportamento da aplicação após a liquidação de um pagamento.

Pré-requisitos

Antes de iniciar os testes, é necessário:

1. Possuir uma conta Sandbox.
2. Possuir uma API Key de Sandbox.
3. Criar um QR Code Pix estático em ambiente Sandbox.
4. Utilizar o endpoint de pagamento de QR Code Pix.

Consulte também:

• Criar QR Code estático
• Pagar um QR Code

Como funciona o teste

O processo consiste em gerar um QR Code Pix estático e, em seguida, utilizar o payload retornado para simular o pagamento.

Fluxo simplificado:

Criar QR Code Pix
        ↓
Obter payload
        ↓
Executar pagamento
        ↓
Criar cobrança Pix
automaticamente
        ↓
Atualizar status
        ↓
Validar integração

Campos importantes da requisição

Ao utilizar o endpoint de pagamento de QR Code Pix, alguns campos possuem papel fundamental:

📘

Importante

O payload deve ser obtido a partir da criação do QR Code Pix em Sandbox.

Os parâmetros completos da requisição estão documentados na referência oficial do endpoint.

Exemplo de requisição

Após criar um QR Code Pix estático em Sandbox, utilize o endpoint de pagamento enviando o payload retornado.

POST /v3/pix/qrCodes/pay

Confira a referência completa deste endpoint

{
  "qrCode": {
    "payload": "00020126710014br.gov.bcb.pix01362ae3db4c-9f04-44de-9a39-adcc98a334c20209Churrasco520400005303986540550.005802BR5913John Doe6009Joinville62290525JHOND00000000465493ASA6304DB5E"
  },
  "value": 50
}

Comportamento esperado

Ao realizar o pagamento:

• uma cobrança Pix será criada automaticamente;
• o pagamento será processado no ambiente Sandbox;
• os identificadores relacionados ao Pix serão vinculados à cobrança;
• sua integração poderá validar os eventos e atualizações decorrentes da operação.

A cobrança criada automaticamente possuirá os campos:

• pixTransaction
• pixQrCodeId

preenchidos com as informações relacionadas à transação simulada.

Diferenças entre Sandbox e Produção

Por esse motivo, recomenda-se validar cuidadosamente os fluxos antes da entrada em produção.

Possíveis dificuldades

Caso o pagamento não seja processado conforme esperado, verifique:

• se o QR Code foi criado em ambiente Sandbox;
• se o payload utilizado corresponde ao QR Code gerado;
• se a autenticação está sendo realizada com uma API Key de Sandbox;
• se os campos obrigatórios da requisição foram enviados corretamente;
• se o valor informado é compatível com o QR Code utilizado.

Boas práticas

📘

Recomendado

• Sempre utilize o payload retornado pela criação do QR Code.
• Valide o recebimento dos webhooks relacionados à cobrança Pix.
• Teste tanto a criação quanto o pagamento do QR Code durante a homologação.
• Não utilize dados de produção durante os testes.
• Monitore as respostas da API para validar o comportamento esperado da integração.

Impactos operacionais

O pagamento de um QR Code Pix pode gerar automaticamente uma cobrança Pix associada à operação.

Por esse motivo, integrações que realizam:

• conciliação financeira;
• controle de recebimentos;
• automações baseadas em cobranças;
• processamento de webhooks;

devem considerar a criação automática dessa cobrança durante os testes e também no ambiente produtivo.

Uma homologação adequada permite validar toda a jornada de recebimento Pix antes da entrada em operação.