MVP Paycheck BR - Validador

O PayCheckBR valida os três meios de pagamento mais comuns do Brasil (Pix, boleto e cartão) lendo a estrutura de cada código, sem consultar banco nenhum. Cada formato segue um padrão público, e o app confere se o código segue esse padrão: os campos certos, na posição certa, com o dígito verificador correto.

É um projeto pessoal de estudo. Na última rodada, apliquei SDD (Spec-Driven Design, Design Orientado por Especificações), refazendo layout, código e documentação a partir de uma especificação escrita antes de programar.

Conceitos fundamentais

Conceito	O que é
Pix (Pagamento Instantâneo Brasileiro)	Sistema de pagamentos do Banco Central. O código de copiar e colar não é um texto qualquer: segue o padrão BR Code, com os campos em posições definidas pelo Manual de Padrões do BACEN.
BR Code	Formato do código Pix, derivado do padrão internacional EMV para QR Code de pagamento. Descreve chave, valor, beneficiário e cidade numa única linha de texto.
boleto	Cobrança bancária identificada por uma linha digitável de 47 números, com banco, valor, vencimento e dígitos de conferência em posições fixas, no padrão FEBRABAN.
dígito verificador	Número calculado a partir dos outros números do código. Serve para o sistema perceber um erro de digitação sem consultar banco nenhum.
checksum (soma de verificação)	A conta que produz o dígito verificador. Cada meio de pagamento usa a sua: Luhn no cartão, Mod10 e Mod11 no boleto, CRC16 no Pix.
SDD (Spec-Driven Design, Design Orientado por Especificações)	Metodologia que exige um contrato de intenção antes de qualquer linha de código.
TLV (Tag-Length-Value, Marcador-Comprimento-Valor)	Estrutura de codificação para organizar campos de pagamento em sequência de bytes.
FEBRABAN (Federação Brasileira de Bancos)	Define o padrão do formato de boletos bancários no Brasil.
IIN/BIN (Issuer/Bank Identification Number, Número de Identificação do Emissor)	Prefixo numérico que identifica a bandeira e o emissor de um cartão de crédito.
Neobrutalism (neobrutalismo)	Estilo visual com bordas rígidas, sombras projetadas e alto contraste cromático.

Stack

Arquitetura e engenharia

O checksum de cada meio de pagamento

Cada um dos três formatos confere a própria integridade com uma conta diferente, e o validador implementa as três:

Meio	Conta	O que ela pega
Cartão	Luhn	Dígito trocado ou dois dígitos vizinhos invertidos no número.
Boleto	Mod10 e Mod11	Erro em cada campo da linha digitável e no código de barras.
Pix	CRC16	Qualquer alteração no código copiado, inclusive nos campos do meio.

Nenhuma delas consulta banco. São contas fechadas sobre o próprio número, e é por isso que a validação roda inteira no navegador.

O reset do fator de vencimento em 2025

O boleto guarda o vencimento como fator de vencimento, um campo de 4 dígitos em que cada unidade vale um dia a partir de uma data base. Quatro dígitos acabam: o ciclo anterior chegou ao fator 9999 em 21/02/2025, e em 22/02/2025 a FEBRABAN reiniciou a contagem em 1000.

Isso cria uma ambiguidade real: o mesmo fator agora aponta para duas datas possíveis, uma em cada ciclo, com cerca de 24 anos de distância. O validador resolve por janela deslizante: quando a data do ciclo antigo cai a mais de 10 anos no passado, o fator é lido como pertencente ao novo ciclo. O fator 0 continua significando “sem vencimento”, à vista.

Destaques da interface

Em cada tipo de validação, as tags TLV (Pix) recebem realce visual e os dígitos verificadores (boleto e cartão) ganham fundo de alto contraste (bg-danger). Assim os campos que mais importam na conferência ficam visíveis de imediato.

Validando um cartão de crédito

Convenções

• Result no lugar de exceção: cada validador devolve isSuccess com o valor, ou isFailure com mensagem e código. O caminho de erro é um retorno como outro qualquer, não um desvio de fluxo.
• Núcleo separado da tela: as regras ficam em src/logic/, sem React e sem DOM, então cada algoritmo é testado sozinho.
• Documentação por meio de pagamento: docs/pix.md, docs/boleto.md e docs/cartao.md registram a anatomia de cada formato, com link para o manual oficial do BACEN e para a especificação da FEBRABAN.

Status

Aspecto	Estado
Maturidade	Projeto de estudo, evolução iterativa
Cobertura de testes	Unit (Vitest) nos três validadores e nos utilitários
Disponibilidade	Live no GitHub Pages
Repositório	Público, licença MIT
Monetização	Nenhuma, projeto de estudo

Os três algoritmos são padrões públicos, e o código que os implementa também: o repositório é público e sob licença MIT, então faça seu fork.