Chave Pix

Chaves Pix nos formatos do DICT: CPF, CNPJ, e-mail, telefone e chave aleatória (EVP).

Validar

Verifica se um valor é uma chave Pix válida: CPF, CNPJ, e-mail, celular brasileiro ou chave aleatória EVP, conforme os formatos de chave do DICT.

Mesmas regras de reconhecimento de pixKey.getInfo.
options pode restringir os tipos de chave aceitos. Uma lista vazia rejeita tudo.
options.accept é uma lista dos tipos de chave que valem como válidos (cpf, cnpj, email, phone, evp). Quando ela falta, ou não é uma lista, todos os tipos são aceitos. Um valor que não é string não é uma chave.

Parâmetro	Tipo	Obrigatório
`value`	`string`	sim
`options`	`IsValidPixKeyOptions`	não
`options.accept`	`PixKeyType[]`	não
retorna	`boolean`

Valida uma chave Pix: um CPF, um CNPJ, um e-mail, um telefone celular brasileiro ou uma chave aleatória EVP, conforme os formatos de chave do DICT.

Opções (IsValidPixKeyOptions): accept (PixKeyType[], padrão todos) lista os tipos de chave aceitos; [] rejeita todos.
Mesmas regras de reconhecimento de getPixKeyInfo.

import { isValidPixKey } from '@brazilian-utils/brazilian-utils';

isValidPixKey('123.456.789-09'); // true
isValidPixKey('[email protected]'); // true
isValidPixKey('(11) 98765-4321'); // true
isValidPixKey('71c7d9be-4b85-4e43-9f1c-1f3b8b4e9a2d'); // true
isValidPixKey('(11) 3000-0000'); // false (telefone fixo não é chave Pix)
isValidPixKey('123.456.789-09', { accept: ['email', 'evp'] }); // false
isValidPixKey('not a key'); // false

Fonte: Manual de Padrões para Iniciação do Pix, API do DICT 2.12.1 e seu changelog, pix-api.

Código: brazilian-utils/javascript

Teste com JavaScript isValidPixKey

Casos de teste compartilhados (39) e o resultado em cada biblioteca pixKey.isValid

Os casos, em JSON

Decodificar

Identifica uma chave Pix e a normaliza para a forma canônica que o DICT espera dentro de um BR Code. Retorna null quando a entrada não é uma chave Pix válida.

O resultado traz o tipo de chave (CPF, CNPJ, e-mail, telefone ou EVP) e o valor canônico: dígitos para CPF ou CNPJ (letras em maiúsculas), e-mail em minúsculas, telefone em E.164 ou UUID em minúsculas.
Espaços nas pontas são ignorados.
Um valor de 11 dígitos válido tanto como CPF quanto como celular é um CPF, a não ser que esteja escrito como telefone (prefixo +55 ou DDD entre parênteses).
Uma chave CPF é reconhecida pela forma como é escrita: os 11 dígitos sem máscara, ou os grupos 3-3-3-2 separados por espaço em branco, ., - ou /, sozinhos ou em sequência, como cpf.isValid lê a máscara. Então 123.456.789-09, 123/456/789/09 e 123 - 456.789 09 são a chave CPF 12345678909. Até a 2.4.0 uma / (ou uma sequência de separadores) entre os grupos impedia que o valor fosse uma chave. Um separador fora dessas posições (1234/56789/09, 1.2.3.4.5.6.7.8.9.0.9) não é um CPF.
Uma chave de telefone tem apenas dígitos, espaços e os +, -, (, ) e . das máscaras usuais, com ou sem o +55. O texto em volta do valor não é removido: abc123.456.789-09, CPF 123.456.789-09 e tel: (11) 98765-4321 não são chaves. Um valor com dígito verificador de CNPJ válido é um CNPJ, mesmo que comece com 0055. O valor E.164 tem no máximo 14 caracteres. O +55 aparece uma só vez, seguido do número nacional de 11 dígitos, então um código de país duplicado (+555511987654321, +55+5511987654321, 0055+5511987654321) não é uma chave, como na 2.4.0.
Uma chave CNPJ é um CNPJ válido de 14 caracteres (dígitos, ou letras no CNPJ alfanumérico), com ou sem máscara, retornado sem máscara e em maiúsculas. Uma chave aleatória EVP é um UUID com a sua pontuação (8-4-4-4-12 dígitos hexadecimais), retornado em minúsculas. Os dígitos de versão e de variante do UUID não são conferidos. Um valor que não é string retorna null.
Telefones fixos não são chaves Pix. Uma chave de telefone segue phone.isValidMobile, então um primeiro dígito do assinante 6 é rejeitado (a 2.4.0 o aceitava).
Uma chave de e-mail é convertida para minúsculas e verificada contra o padrão da API do DICT 2.12.1 e seu limite de 77 caracteres, não contra email.isValid. A parte local pode ter qualquer um de .!#$'*+/=?^_`{|}~-, com pontos em qualquer posição, e o domínio pode ter um só rótulo. Cada rótulo do domínio tem letras, dígitos e hífens, com no máximo 63 caracteres. Então fulano@example, a@localhost e a{b}@example.com são chaves; a 2.4.0 verificava a chave com email.isValid e as rejeitava.
O & não é permitido em uma chave de e-mail: a API do DICT 2.6.0 o removeu do padrão. a&[email protected] não é uma chave.
Retorna null exatamente quando pixKey.isValid retorna false.

Parâmetro	Tipo	Obrigatório
`value`	`string`	sim
retorna	`PixKeyInfo \| null`

Identifica uma chave Pix e a normaliza para a forma canônica que o DICT espera dentro de um BR Code. Retorna null quando o valor não é uma chave Pix válida.

Retorna um PixKeyInfo com o type (PixKeyType) e o value.
O value canônico é só dígitos para CPF ou CNPJ (letras maiúsculas), e-mail minúsculo, celular em E.164 ou UUID minúsculo.
Um valor de 11 dígitos válido como CPF e celular é lido como CPF, salvo se escrito como telefone (prefixo +55 ou DDD entre parênteses).
Um e-mail é conferido, já em minúsculas, contra a expressão regular que a API do DICT registra e o limite de 77 caracteres, não contra isValidEmail: a parte local pode ter qualquer um de .!#$'*+/=?^_`{|}~-, pontos em qualquer posição inclusive, e o domínio pode ter um só rótulo (a@localhost). A expressão é a da API do DICT 2.12.1, que não tem & desde a versão 2.6.0 (27/09/2025).

import { getPixKeyInfo } from '@brazilian-utils/brazilian-utils';

getPixKeyInfo('123.456.789-09'); // { type: 'cpf', value: '12345678909' }
getPixKeyInfo('[email protected] '); // { type: 'email', value: '[email protected]' }
getPixKeyInfo('a{b}@example.com'); // { type: 'email', value: 'a{b}@example.com' } (expressão do DICT, isValidEmail o rejeita)
getPixKeyInfo('a&[email protected]'); // null (sem & desde a API do DICT 2.6.0)
getPixKeyInfo('(11) 98765-4321'); // { type: 'phone', value: '+5511987654321' }
getPixKeyInfo('71C7D9BE-4B85-4E43-9F1C-1F3B8B4E9A2D');
// { type: 'evp', value: '71c7d9be-4b85-4e43-9f1c-1f3b8b4e9a2d' }
getPixKeyInfo('(11) 3000-0000'); // null (telefone fixo não é chave Pix)
getPixKeyInfo('51998259765'); // { type: 'cpf', value: '51998259765' } (também é um telefone válido)
getPixKeyInfo('+5551998259765'); // { type: 'phone', value: '+5551998259765' }

Fonte: Manual de Padrões para Iniciação do Pix, API do DICT 2.12.1 e seu changelog.

Código: brazilian-utils/javascript

Teste com JavaScript getPixKeyInfo

Casos de teste compartilhados (70) e o resultado em cada biblioteca pixKey.getInfo

Os casos, em JSON

Fontes oficiais

Veja também Pix copia e cola (BR Code), CPF, CNPJ, Telefone, E-mail

Chave Pix

Validar

Decodificar

Fontes oficiais

Nesta página