# PixCode

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.

```tsx
<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.

```tsx
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.

```tsx
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.

```tsx
<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.

```tsx
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.

## Importação

```tsx
import { PixCode } from '@rivocode/ui'
```

## Exemplos

### Cobrança com valor

```tsx
import { PixCode, buildPixPayload } from '@rivocode/ui'

const COBRANCA = buildPixPayload({
  key: '+5583988112233',
  name: 'Clínica Coração Saudável',
  city: 'João Pessoa',
  amount: 1284.5,
  txid: 'CONSULTA4813',
  description: 'Consulta de 12/09',
})

export function Charge() {
  return <PixCode payload={COBRANCA} />
}
```

### Enquanto a cobrança é gerada

```tsx
import { PixCode, buildPixPayload } from '@rivocode/ui'

export function Loading() {
  return <PixCode payload="" loading amount={1284.5} />
}
```

### Código vencido

```tsx
import { PixCode, buildPixPayload } from '@rivocode/ui'

const COBRANCA = buildPixPayload({
  key: '+5583988112233',
  name: 'Clínica Coração Saudável',
  city: 'João Pessoa',
  amount: 1284.5,
  txid: 'CONSULTA4813',
  description: 'Consulta de 12/09',
})

export function Expired() {
  return <PixCode payload={COBRANCA} expired onRenew={() => {}} />
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `payload` | `string` | sim |  | - | O Pix copia e cola inteiro, como o PSP ou o `buildPixPayload` devolvem. |
| `amount` | `number` |  |  | - | O valor em reais que aparece em destaque. |
| `classNames` | `Partial<Record<"amount" \| "code" \| "copy" \| "countdown" \| "payload" \| "receiver", string>>` |  |  | - | Classe por parte: `code`, `amount`, `receiver`, `payload`, `copy`, `countdown`. |
| `expired` | `boolean` |  | `false` | - | Troca o QR por um aviso e tira o copiar: codigo vencido nao se oferece para pagar. |
| `expiresAt` | `string \| number \| Date` |  |  | - | Quando o codigo vence: `Date`, texto ISO ou milissegundos. |
| `labels` | `Partial<PixCodeLabels>` |  |  | - | Os textos da peca, para quem precisa de outro idioma ou outro tom. |
| `loading` | `boolean` |  | `false` | - | Enquanto a cobranca e gerada: marca de lugar no QR e no texto, com `aria-busy`, e o aviso na regiao viva. |
| `onExpire` | `(() => void)` |  |  | - | Chamado uma vez quando o `expiresAt` passa. |
| `onRenew` | `(() => void)` |  |  | - | Liga o botao de gerar outro codigo, no aviso de expirado. |
| `receiver` | `string` |  |  | - | O nome do recebedor como a tela deve mostrar, com acento. |
| `size` | `number` |  | `192` | - | O lado do QR em px. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [AudioPlayer](/componentes/audio-player.md)
- [Code](/componentes/code.md)
- [EventCalendar](/componentes/event-calendar.md)
- [Gantt](/componentes/gantt.md)
- [Kanban](/componentes/kanban.md)
- [QRCode](/componentes/qr-code.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
