Skip to main content
Receber via Pix, na prática, significa gerar um QR Code de cobrança que o seu pagador escaneia (ou copia e cola) no aplicativo do banco dele. Assim que o pagamento é liquidado no Banco Central, você recebe uma notificação em tempo real via webhook, e o valor cai na sua conta. Toda cobrança Pix na API segue o mesmo ciclo de vida, o que muda entre os modelos é quem define o valor, quantas vezes o QR Code pode ser pago e por quanto tempo ele fica válido. Escolher o modelo certo aqui evita retrabalho de integração mais adiante.

​
Modelos de cobrança disponíveis

Cobrança Reutilizável

QR Code Estático. Um único código, reutilizável indefinidamente. Ideal para valores livres ou fixos em pontos de venda, doações e caixinhas.

Cobrança Imediata

QR Code Dinâmico. Um código novo por cobrança, com expiração curta. Ideal para checkout de e-commerce e cobranças pontuais.

Cobrança com Vencimento

QR Code com Vencimento (cobv). Cobrança com data de vencimento, juros, multa e desconto. Ideal para boletos, mensalidades e faturas.

​
Qual modelo escolher?

Cobrança Reutilizável
(QR Estático)		Cobrança Imediata
(QR Dinâmico)		Cobrança com Vencimento
(cobv)
Quantidade de pagamentos por QR CodeIlimitadaÚnicaÚnica
ValorFixo, livre ou ausenteDefinido na criaçãoDefinido na criação
Expira?Não (até ser cancelado)Sim, minutos após a criaçãoSim, dias/meses após a criação
Juros, multa e descontoNãoNãoSim
Identifica automaticamente o pagador de qual pedido?NãoSimSim
Casos de uso comunsPonto de venda físico, doações, caixinhaCheckout de e-commerce, cobrança avulsaFaturas, mensalidades, substituição de boleto
Se você está migrando de boleto para Pix, o modelo mais próximo é a Cobrança com Vencimento, já que ela preserva conceitos como data de vencimento, multa e desconto por antecipação.

​
Como funciona, de ponta a ponta

Independentemente do modelo escolhido, toda cobrança Pix segue o mesmo fluxo:
  1. Você cria a cobrança informando os dados necessários (valor, expiração, identificador, dados do pagador quando aplicável).
  2. A API responde com o pix_copy_paste (o payload Pix em texto, no padrão BR Code) e os dados para você mesmo renderizar o QR Code, ou uma imagem já pronta, dependendo do endpoint.
  3. Você apresenta o código ao pagador — na tela de checkout, num totem, num app, por e-mail etc.
  4. O pagador paga no aplicativo do banco dele. A liquidação acontece em segundos.
  5. Você é notificado via webhook assim que o pagamento é confirmado — é esse evento que deve disparar a baixa do pedido no seu sistema, não uma consulta em polling.
  6. Opcionalmente, você pode consultar o status da cobrança a qualquer momento pelos endpoints de consulta.
Não use consulta por polling como mecanismo principal de confirmação de pagamento. Os webhooks existem justamente para eliminar essa necessidade e evitar rate limiting desnecessário. Use a consulta apenas para reconciliação ou recuperação de falhas.

​
Próximos passos

Cobrança Reutilizável (QR Estático)

Crie, consulte e cancele um QR Code reutilizável.

Cobrança Imediata (QR Dinâmico)

Crie uma cobrança de uso único com expiração, split e beneficiário final.

Cobrança com Vencimento

Crie cobranças com data de vencimento, juros, multa e desconto.

Processando a confirmação via Webhook

Configure e trate o evento PIX_RECEIVED corretamente.