Testar pagamento de QRCodes Pix

Utilize o Sandbox para homologar o pagamento de um QR Code Pix sem movimentar valores reais.

Neste fluxo, uma conta Sandbox gera o QR Code e outra conta, com saldo disponível, realiza o pagamento.

Quando utilizar

Use este fluxo para testar:

• pagamentos de QR Codes Pix;
• atualização do saldo da conta pagadora;
• recebimento do valor na conta de destino;
• processamento de transações Pix;
• Webhooks relacionados à operação;
• conciliação entre pagamento e recebimento.

Antes de começar

Você precisa:

1. Ter duas contas Sandbox:
   • uma conta de destino, que criará o QR Code;
   • uma conta pagadora, que realizará o pagamento.
2. Gerar uma chave de API para cada conta.
3. Possuir saldo disponível na conta pagadora.
4. Ter uma chave Pix cadastrada na conta de destino.
5. Configurar os Webhooks utilizados pela integração.

Caso a conta pagadora não tenha saldo, consulte Adicione saldo à sua conta Sandbox.

Como funciona

Conta Sandbox de destino
        ↓
Criar QR Code Pix
        ↓
Obter o payload
        ↓
Conta Sandbox pagadora
        ↓
Pagar o QR Code
        ↓
Validar saldo, status e Webhooks

1. Crie o QR Code Pix

Na conta Sandbox de destino, utilize o endpoint de criação de QR Code estático.

Consulte o endpoint Criar QR Code estático.

Armazene o valor retornado no campo payload, pois ele será utilizado no pagamento.

2. Pague o QR Code

Na conta Sandbox pagadora, envie o payload para o endpoint:

POST /v3/pix/qrCodes/pay

Consulte a referência do endpoint.

Exemplo de requisição

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

Os principais campos são:

Consulte a referência para conhecer todas as regras de preenchimento.

3. Valide o resultado

Após enviar a requisição:

1. confira o status HTTP e o corpo da resposta;
2. armazene o ID da transação;
3. acompanhe o status do pagamento;
4. valide o débito na conta pagadora;
5. valide o recebimento na conta de destino;
6. confirme o processamento dos Webhooks.

Comportamento esperado

No Sandbox:

• nenhum valor real é movimentado;
• nenhuma instituição financeira é acionada;
• o saldo da conta pagadora é atualizado;
• a conta de destino recebe o valor simulado;
• os recursos relacionados à transação Pix ficam disponíveis para consulta;
• os Webhooks configurados podem ser utilizados para validar o processamento.

Caso o recebimento gere uma cobrança automática na conta de destino, utilize os campos relacionados ao Pix para identificar sua origem.

Caso o pagamento não seja criado

Verifique se:

• o QR Code foi criado no Sandbox;
• o payload foi copiado por completo;
• a conta pagadora possui saldo;
• a chave Pix da conta de destino está cadastrada;
• a URL e a chave de API pertencem ao Sandbox;
• o valor informado é compatível com o QR Code;
• os campos obrigatórios foram enviados corretamente.

Diferenças entre Sandbox e Produção

O sucesso da operação no Sandbox não garante a conclusão de qualquer pagamento em Produção.

Checklist de homologação

Antes de considerar o fluxo homologado, confirme se sua aplicação:

• valida o saldo antes do pagamento;
• armazena o ID da transação;
• acompanha as alterações de status;
• processa os Webhooks de forma idempotente;
• diferencia a conta pagadora da conta recebedora;
• evita pagamentos duplicados;
• registra logs e mensagens de erro;
• utiliza credenciais correspondentes ao ambiente.

Próximos passos

• Crie um QR Code Pix estático
• Pague um QR Code Pix
• Adicione saldo à conta Sandbox
• Teste outras funcionalidades no Sandbox