Formato da chave Pix

Toda chave Pix enviada para a API (no pagamento, na consulta de chave, na criação de subconta e nos splits) tem que estar no formato do seu tipo. O tipo da chave é identificado pelo formato, e um formato errado pode fazer a chave ser lida como outro tipo.

Formato por tipo

Tipo	Formato	Exemplo
CPF	11 dígitos, sem pontuação	00000000191
CNPJ	14 dígitos, sem pontuação	00000000000191
PHONE	formato internacional E.164: +, DDI, DDD e número	+5511912345684
EMAIL	o endereço de e-mail	[email protected]
RANDOM	a chave aleatória (EVP), UUID de 36 caracteres	c4249323-b4ca-43f2-8139-8232aab09b93

Telefone

A chave de telefone é sempre enviada no formato internacional E.164, só com o sinal + e dígitos, sem espaços, parênteses ou hífen:

+ DDI DDD número

• DDI: o código do país. Para o Brasil, 55.
• DDD: o código de área com 2 dígitos, sem o 0 (ex.: 11 para São Paulo, 21 para o Rio de Janeiro).
• Número: o número do telefone. Para celular no Brasil, 9 dígitos, começando com 9.

Como o número aparece	Como enviar
(11) 91234-5684	+5511912345684
11 91234-5684	+5511912345684
011 91234-5684	+5511912345684
+55 (11) 91234-5684	+5511912345684

Telefone sem +55

Um número só com dígitos que seja um CPF válido é lido como CPF, mesmo que também seja um celular. Muitos celulares também são CPFs válidos: 11912345684, por exemplo, é ao mesmo tempo um celular de DDD 11 e um CPF. Enviado sem +55, o Pix vai para o dono do CPF 11912345684, e não para o dono do telefone.

Envie sempre o telefone com +55 e informe o tipo da chave (destinationAliasType: "PHONE" no pagamento).

Chave ambígua: CPF ou telefone

Uma chave só com dígitos que é ao mesmo tempo um CPF válido e um celular brasileiro (ex.: 11912345684) é ambígua: sem o tipo, não dá para saber se ela é o CPF ou o telefone.

A API recusa com 400 uma chave ambígua enviada sem o tipo, em vez de tratá-la como CPF. Para que a chave seja aceita, informe o tipo correto:

• se é o CPF, envie o tipo CPF com os 11 dígitos (11912345684);
• se é o telefone, envie o tipo PHONE com o número no formato internacional (+5511912345684).

O tipo é informado no campo de cada endpoint:

Endpoint	Campo da chave	Campo do tipo
POST /api/v1/payment	destinationAlias	destinationAliasType
POST /api/v1/subaccount	pixKey	pixKeyType
POST /api/v1/charge (splits)	splits[].pixKey	splits[].pixKeyType
POST /api/v1/pix-keys/withdraw e PUT /api/v1/pix-keys/withdraw	pixKey	pixKeyType
POST /api/v1/stablecoin/payout	pixKey	pixKeyType

Exemplos de pagamento:

{
  "value": 100,
  "destinationAlias": "+5511912345684",
  "destinationAliasType": "PHONE",
  "correlationID": "31ee9576-99ec-412a-9ac7-e142a4a6acf0"
}

{
  "value": 100,
  "destinationAlias": "11912345684",
  "destinationAliasType": "CPF",
  "correlationID": "8a1d3c6e-6f2b-4f0e-9b7a-1c2d3e4f5a6b"
}

Resposta para uma chave ambígua enviada sem o tipo:

{
  "error": "destinationAlias is valid for more than one Pix key type (CPF, PHONE). Please inform destinationAliasType"
}

Nos outros endpoints a mensagem é a mesma, com o nome do campo do tipo (pixKeyType); na criação de subconta ela vem com errorCode: "AMBIGUOUS_PIX_KEY".

Mesmo para chaves que não são ambíguas, sempre informe o tipo da chave.

Consulta de chave

A consulta de chave Pix segue o mesmo formato. Para consultar um telefone, envie +5511912345684; o campo type da resposta mostra o tipo da chave que foi consultada.