QR Code

A criação da cobrança devolve duas formas do mesmo PIX, dentro de pix:

• payload é o BR Code em texto, o "copia e cola" que o cliente cola no app do banco.
• qr_base64 é a mesma coisa já desenhada, uma imagem PNG codificada em base64.

As duas apontam para o mesmo pagamento. Mostrar as duas na tela é o padrão que menos gera suporte: o QR para quem está no computador e paga pelo celular, o copia e cola para quem já está no celular.

Mostrar a imagem

qr_base64 entra direto num img, sem biblioteca:

<img alt="QR Code do PIX" src="data:image/png;base64,COLE_AQUI_O_qr_base64" />

Se você preferir desenhar no seu próprio estilo, gere o QR a partir do payload com qualquer biblioteca de QR Code. O conteúdo do QR é exatamente a string do payload, sem prefixo, sem URL e sem transformação.

Mostrar o copia e cola

Um campo somente leitura com um botão que copia o payload inteiro. Três cuidados que resolvem quase todo chamado de "o PIX não funciona":

• Copie a string inteira, sem quebra de linha e sem espaço no fim.
• Não deixe o campo editável.
• Não aplique máscara, nem quebra visual em blocos. O que é bonito na tela quebra o pagamento se for copiado junto.

O que nunca fazer com o payload

Não reconstrua o BR Code. Não gere um payload a partir de uma chave PIX sua, não recalcule o dígito de verificação, não troque o valor, não concatene um identificador. O payload é emitido pelo processador e qualquer alteração o invalida, na melhor das hipóteses. Na pior, o dinheiro vai para o lugar errado e a cobrança nunca é conciliada.

Não interprete o conteúdo. Não faça parse para extrair valor, chave ou beneficiário e mostrar na tela. Esses dados já estão nos próprios campos da cobrança, que são estáveis; o formato interno do BR Code não é contrato nosso.

Não faça cache entre cobranças. Cada cobrança tem o payload dela. Reaproveitar o de outra faz dois clientes pagarem a mesma coisa, e só uma das duas é conciliada.

Quando não existe QR

payload e qr_base64 são nulos quando a cobrança está failed, isto é, quando o processador recusou ou não respondeu na criação. Confira antes de renderizar, e trate esse caso como erro de checkout, não como tela em branco.

pix.expires_at vem sempre, inclusive nesse caso. Ele é o prazo real, e nem sempre é o que você pediu: ver Expiração.

Próximo passo

Expiração.

Referência: Cria uma cobrança PIX e Consulta uma cobrança.