Pix key

Validate

Checks whether a value is a valid Pix key: a CPF, a CNPJ, an email, a Brazilian mobile phone or a random EVP key, per the DICT key formats.

Same recognition rules as pixKey.getInfo.
options can restrict the accepted key types. An empty list rejects everything.
options.accept is a list of the key types that count as valid (cpf, cnpj, email, phone, evp). When it is missing, or not a list, every type is accepted. A value that is not a string is not a key.

Parameter	Type	Required
`value`	`string`	yes
`options`	`IsValidPixKeyOptions`	no
`options.accept`	`PixKeyType[]`	no
returns	`boolean`

Check if a Pix key (chave Pix) is valid: a CPF, a CNPJ, an e-mail address, a Brazilian mobile phone number or a random EVP key, per the DICT key formats.

Options (IsValidPixKeyOptions): accept (PixKeyType[], default all of them) lists the kinds of key that count as valid; [] rejects everything.
Same recognition rules as getPixKeyInfo.

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

isValidPixKey('123.456.789-09'); // true
isValidPixKey('fulano@example.com'); // true
isValidPixKey('(11) 98765-4321'); // true
isValidPixKey('71c7d9be-4b85-4e43-9f1c-1f3b8b4e9a2d'); // true
isValidPixKey('(11) 3000-0000'); // false (landlines are not Pix keys)
isValidPixKey('123.456.789-09', { accept: ['email', 'evp'] }); // false
isValidPixKey('not a key'); // false

Source: Manual de Padrões para Iniciação do Pix, DICT API 2.12.1 and its changelog, pix-api.

Code: brazilian-utils/javascript

Try it with JavaScript isValidPixKey

Shared test cases (39) and the result in each library pixKey.isValid

The cases, as JSON

Decode

Identifies a Pix key and normalizes it to the canonical form the DICT expects inside a BR Code. Returns null when the value is not a valid Pix key.

The result has the key type (CPF, CNPJ, email, phone or EVP) and the canonical value: digits for a CPF or CNPJ (letters upper-cased), a lowercase email, an E.164 phone or a lowercase UUID.
Leading and trailing whitespace is ignored.
An 11-digit value valid as both CPF and mobile phone is a CPF, unless written as a phone (+55 prefix or DDD in parentheses).
A CPF key is recognized by the way it is written: the bare 11 digits, or the groups 3-3-3-2 split by whitespace, ., - or /, alone or in a run, as cpf.isValid reads its mask. So 123.456.789-09, 123/456/789/09 and 123 - 456.789 09 are the CPF key 12345678909. Until 2.4.0 a / (or a run of separators) between the groups made it not a key. A separator outside those positions (1234/56789/09, 1.2.3.4.5.6.7.8.9.0.9) is not a CPF.
A phone key holds only digits, spaces and the +, -, (, ) and . of the usual masks, with or without the +55. Text around the value is not stripped: abc123.456.789-09, CPF 123.456.789-09 and tel: (11) 98765-4321 are not keys. A value with a valid CNPJ check digit is a CNPJ, even when it starts with 0055. The E.164 value has at most 14 characters. The +55 appears once, followed by the 11-digit national number, so a doubled country code (+555511987654321, +55+5511987654321, 0055+5511987654321) is not a key, as in 2.4.0.
A CNPJ key is a valid CNPJ of 14 characters (digits, or letters for the alphanumeric CNPJ), with or without its mask, returned unmasked and upper-cased. A random EVP key is a UUID with its punctuation (8-4-4-4-12 hexadecimal digits), returned in lowercase. The version and variant digits of the UUID are not checked. A value that is not a string gives null.
Landlines are not Pix keys. A phone key follows phone.isValidMobile, so a first subscriber digit of 6 is rejected (2.4.0 accepted it).
An email key is lowercased and checked against the pattern of the DICT API 2.12.1 and its limit of 77 characters, not against email.isValid. The local part may carry any of .!#$'*+/=?^_`{|}~-, with dots anywhere, and the domain may be a single label. Each domain label has letters, digits and hyphens, at most 63 characters. So fulano@example, a@localhost and a{b}@example.com are keys; 2.4.0 checked the key with email.isValid and rejected them.
The & is not allowed in an email key: DICT API 2.6.0 removed it from the pattern. a&b@example.com is not a key.
Returns null exactly when pixKey.isValid returns false.

Parameter	Type	Required
`value`	`string`	yes
returns	`PixKeyInfo \| null`

Identify a Pix key and normalize it to the canonical form the DICT expects inside a BR Code. Returns null when the value is not a valid Pix key.

Returns a PixKeyInfo with the type (PixKeyType) and the value.
The canonical value is digits for a CPF or CNPJ (letters upper-cased), a lowercase e-mail, an E.164 phone or a lowercase UUID.
An 11 digit value valid as both CPF and mobile phone is read as a CPF, unless written as a phone (+55 prefix or DDD in parentheses).
An e-mail is checked, once lowercased, against the pattern the DICT API registers and its 77 character limit, not against isValidEmail: the local part may carry any of .!#$'*+/=?^_`{|}~-, dots included anywhere, and the domain may be a single label (a@localhost). The pattern is the one of DICT API 2.12.1, which has had no & since version 2.6.0 (27/09/2025).

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

getPixKeyInfo('123.456.789-09'); // { type: 'cpf', value: '12345678909' }
getPixKeyInfo('Fulano@Example.COM '); // { type: 'email', value: 'fulano@example.com' }
getPixKeyInfo('a{b}@example.com'); // { type: 'email', value: 'a{b}@example.com' } (DICT pattern, isValidEmail rejects it)
getPixKeyInfo('a&b@example.com'); // null (no & since DICT API 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 (a landline is not a Pix key)
getPixKeyInfo('51998259765'); // { type: 'cpf', value: '51998259765' } (also a valid phone)
getPixKeyInfo('+5551998259765'); // { type: 'phone', value: '+5551998259765' }

Source: Manual de Padrões para Iniciação do Pix, DICT API 2.12.1 and its changelog.

Code: brazilian-utils/javascript

Try it with JavaScript getPixKeyInfo

Shared test cases (70) and the result in each library pixKey.getInfo

The cases, as JSON

Official sources

See also Pix payload (BR Code), CPF, CNPJ, Phone, Email

Pix key

Validate

Decode

Official sources

On this page