Pular para o conteúdo
Dados

PixCode

/componentes/pix-code.mdmarkdown cru, para quem lê com agent em vez de olho

Cobrança com valor

R$ 1.284,50

para Clinica Coracao Saudavel

Pix copia e cola

00020126570014br.gov.bcb.pix0114+55839881122330217Consulta de 12/0952040000530398654071284.505802BR5924Clinica Coracao Saudavel6011Joao Pessoa62160512CONSULTA481363046649

Enquanto a cobrança é gerada

Gerando o código Pix…

R$ 1.284,50

Pix copia e cola

Código vencido

Este código Pix expirou.

Este código Pix expirou.

R$ 1.284,50

para Clinica Coracao Saudavel

Importar
import { PixCode } from '@rivocode/ui'

Quando usar

A cobrança por Pix inteira num cartão: o QR Code, o valor em destaque, o nome de quem recebe e o copia e cola com o botão de copiar.

Ela recebe o copia e cola pronto, como o PSP devolve na cobrança dinâmica ou como o buildPixPayload monta na estática, e confere o CRC antes de desenhar. Código com o dígito errado não vira QR: vira aviso, porque um QR que o banco recusa é pior do que nenhum.

<PixCode payload={cobranca.pixCopiaECola} />

O valor e o nome saem do próprio código (campos 54 e 59). amount e receiver vencem os dois: use-os quando a tela sabe mais do que o código diz. O nome gravado no código é ASCII, sem acento (o buildPixPayload tira), então a "Clínica Coração Saudável" aparece como "Clinica Coracao Saudavel"; passe o nome com acento em receiver para a tela e o leitor de tela dizerem certo.

O copia e cola é aparado antes de tudo: espaço e quebra de linha que vieram colados da resposta do PSP não entram no QR nem no que o botão copia. No QR dinâmico o valor gravado no código não aparece, porque o manual do Banco Central manda o pagador ignorá-lo e ler o da cobrança; ali o valor entra só por amount.

O QR sai escuro sobre claro em qualquer tema, numa placa branca de canto arredondado dentro do cartão. No tema escuro o cartão fica escuro e a placa não: módulo claro sobre fundo escuro é um código que parte dos apps de banco não lê, e um Pix que o banco não lê é um pagamento que não acontece. Não envolva a peça num RivoProvider claro para isso; a regra é da peça, e vale também para tema de cliente. O porquê está em QRCode.

O copiar é o Clipboard da casa, com a confirmação que troca o nome do botão. No celular do pagador o copia e cola é o caminho principal, e não o reserva: ninguém aponta a câmera para a própria tela.

Montar o código

buildPixPayload monta o BR Code estático do Pix pelo Manual de Padrões para Iniciação do Pix do BCB: o GUI br.gov.bcb.pix com a chave e o texto livre no campo 26, moeda 986, país BR, nome e cidade, o txid no 62/05 (ou ***, como o manual manda quando não há) e o CRC16-CCITT no 63.

const payload = buildPixPayload({
  key: '+5583988112233',
  name: 'Clínica Coração Saudável',
  city: 'João Pessoa',
  amount: 1284.5,
  txid: 'CONSULTA4813',
})

O acento sai do nome, da cidade e do texto livre, e a letra fica: "Jørgen Ångström" vira "Jorgen Angstrom". O código sai inteiro em ASCII, porque o tamanho de cada campo e o CRC são contados em caractere e o QR grava byte, e banco nenhum garante o resto.

A chave é gravada como o DICT a guarda: CPF e CNPJ perdem a pontuação, celular digitado com máscara ganha o +55, e-mail e chave aleatória descem para minúsculas. Chave que depois disso não passa no isValidPixKey é recusada com RangeError, porque um código com chave que o DICT não acha é cobrança que não paga. O valor é arredondado ao centavo antes de conferir: 0.004 é recusado, e 1.005 grava 1.01. O que passa dos limites do manual e do EMV (chave até 77, nome até 25, cidade até 15, txid até 25 letras e dígitos, chave mais texto livre até 99) é recusado com RangeError, e não cortado: nome cortado em silêncio é cobrança que ninguém reconhece.

parsePixPayload faz o caminho de volta e devolve null quando o CRC não confere ou o código não é Pix. Ele lê o estático, o dinâmico (url no lugar da chave, e unique quando o código só vale um pagamento) e o composto (recurrence).

isValidPixKey aceita a chave como a pessoa digita e confere como o DICT a guarda: antes de olhar, ela passa por normalizePixKey, o mesmo passo do buildPixPayload, e o que um aceita o outro aceita. CPF e CNPJ (inclusive o alfanumérico) pontuados ou não, com o dígito verificador certo; celular com máscara, como (61) 91234-5678, ou já com +55; e-mail e chave aleatória em qualquer caixa. Para gravar, use o que normalizePixKey devolve: 52998224725, e não 529.982.247-25. O parsePixPayload recusa o código cujo campo 54 não é valor em reais maior que zero, com até duas casas: -5, 1e3 e 0x10 não passam.

Estados

loading põe marca de lugar no QR e no texto, com aria-busy, e o copiar fica desligado. expired troca o QR por um aviso e tira o copiar: código vencido não se oferece para pagar. Com onRenew, o aviso ganha o botão de gerar outro.

Os dois chegam ao leitor de tela por uma região viva que a peça monta sempre, e que só troca de texto: "Gerando o código Pix…" enquanto carrega, "Código Pix pronto." quando termina, e o aviso de expirado quando vence. Região que nasce junto com o texto não é anunciada, e aria-busy sozinho não é lido por ninguém.

O prazo

expiresAt recebe quando o código vence (Date, texto ISO ou milissegundos, como o PSP devolve) e a peça faz a conta: "Vence em 14:32" logo abaixo do valor, em algarismos de largura fixa, e no fim troca o QR pelo aviso de expirado sozinha, como expired. onExpire é chamado uma vez quando o prazo passa, para a tela parar de consultar a cobrança.

A contagem visível não é região viva: anunciar cada segundo atropela o leitor de tela. O prazo é dito uma vez ("O código Pix vence em 15 minutos.") e de novo no último minuto, e o vencido é dito quando vence. Se o foco estava dentro da peça, ele vai para o "Gerar novo código", porque o botão de copiar some. A conta segue o relógio, e não um contador: quem sai do app para pagar no banco e volta vê o que sobrou.

const { mutate: renew } = useMutation({ mutationFn: renewCharge })

<PixCode
  payload={charge.data.pixCopiaECola}
  expiresAt={charge.data.expiresAt}
  onExpire={() => charge.refetch()}
  onRenew={() => renew(order.id)}
/>

Partes

classNames alcança code (o QR, a marca de lugar ou o aviso de expirado), amount, receiver, payload (o texto do copia e cola), copy (o botão) e countdown (o "Vence em"). labels troca os textos, e o tipo sai como PixCodeLabels: copy, copied, payload, expired, renew, invalid, loading, ready e lastMinute, mais as funções receiver(nome), a linha "para Fulano", code(valor, nome), o nome do QR para o leitor de tela, expiresIn(tempo), o prazo visível, e expiresSoon(tempo), o prazo dito.

<PixCode
  payload={payload}
  labels={{ receiver: (name) => `to ${name}`, code: (amount, name) => `Pix QR ${amount} ${name}` }}
/>

Quando não usar

  • Para um QR Code que não é Pix, como o link do cardápio de um restaurante, use QRCode: ele desenha o código sem conferir CRC nem mostrar valor.
  • Para mostrar a chave Pix solta, que quem paga copia para o próprio banco, use Code com um Clipboard ao lado. O campo em que alguém escreve a chave é um Input, conferido por isValidPixKey. A chave não é o copia e cola, e um QR dela não leva valor nem txid.

No React Native

Traduz, no caminho @rivocode/ui-native/chart, porque o QR é o QRCode nativo, desenhado com o react-native-svg. As funções puras (buildPixPayload, parsePixPayload e isValidPixKey) saem da raiz: não pedem peer nenhum, e o arquivo é o mesmo do web, pelo espelho do código compartilhado. O valor sai formatado sem Intl, igual nos dois lados.

O copiar entra por renderCopy. O Clipboard nativo mora em @rivocode/ui-native/clipboard por causa do expo-clipboard, e a regra da casa é um subcaminho por peer: se a peça o importasse, quem desenha um QR teria de instalar o módulo de área de transferência. A função recebe o copia e cola e só é chamada quando há o que copiar (nem carregando, nem expirado, nem com o CRC errado), então o botão some junto com o código. O texto é selectable de todo jeito, e o toque longo copia mesmo sem o botão.

import { PixCode } from '@rivocode/ui-native/chart'
import { Clipboard } from '@rivocode/ui-native/clipboard'

<PixCode
  payload={cobranca.pixCopiaECola}
  renderCopy={(payload) => <Clipboard value={payload}>Copiar código</Clipboard>}
/>

As partes vestem pelo mesmo classNames do web: code, amount, receiver e payload. copy não porta: o botão é o que o renderCopy devolve, e quem o escreve já o veste.

O prazo vence sozinho, como no web. Com expiresAt (Date, texto ISO ou milissegundos) a peça mostra "Vence em 14:32" perto do valor, na parte countdown, e no fim troca o QR pelo aviso de expirado e chama o onExpire uma vez. O leitor de tela ouve o prazo uma vez e de novo no último minuto, e nunca cada segundo. A conta segue o relógio, então quem sai do app para pagar e volta vê o que sobrou. A conta do prazo é a mesma função do web, em shared/pix.ts. O que não atravessa é o foco que pula para o "Gerar novo código": aqui não há foco de teclado a mover.

No iOS e no Android. No Android 13 ou mais novo, o próprio sistema mostra uma confirmação ao copiar, além do aviso “Copiado” da peça. O aviso da peça fica nos dois para o iOS, que não mostra nada.

API

PropTipoPadrão
payloadobrigatória

O Pix copia e cola inteiro, como o PSP ou o `buildPixPayload` devolvem.

stringsem padrão
amount

O valor em reais que aparece em destaque.

numbersem padrão
classNames

Classe por parte: `code`, `amount`, `receiver`, `payload`, `copy`, `countdown`.

Partial<Record<"amount" | "code" | "copy" | "countdown" | "payload" | "receiver", string>>sem padrão
expired

Troca o QR por um aviso e tira o copiar: codigo vencido nao se oferece para pagar.

booleanfalse
expiresAt

Quando o codigo vence: `Date`, texto ISO ou milissegundos.

stringnumberDatesem padrão
labels

Os textos da peca, para quem precisa de outro idioma ou outro tom.

Partial<PixCodeLabels>sem padrão
loading

Enquanto a cobranca e gerada: marca de lugar no QR e no texto, com `aria-busy`, e o aviso na regiao viva.

booleanfalse
onExpire

Chamado uma vez quando o `expiresAt` passa.

(() => void)sem padrão
onRenew

Liga o botao de gerar outro codigo, no aviso de expirado.

(() => void)sem padrão
receiver

O nome do recebedor como a tela deve mostrar, com acento.

stringsem padrão
size

O lado do QR em px.

number192

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.