OnnixPay

PIX

Consultar chave PIX

Resolve qualquer chave PIX no DICT, inclusive de terceiros, e devolve o titular e a instituição. É a primeira etapa obrigatória de todo pagamento por chave: o end_to_end_id devolvido aqui é exigido em POST /v1/payouts.

POST/v1/pix/dict/lookup

Headers

x-api-keystringobrigatório
Sua chave de API com escopo pix:read.

Corpo da requisição

keystringobrigatório
A chave a consultar: CPF, CNPJ, e-mail, telefone (+5511999999999) ou chave aleatória.
key_typestringopcional
Tipo da chave: cpf, cnpj, email, phone ou evp. Recomendado. Um valor de 11 dígitos pode ser um CPF ou um celular sem DDI, e sem esse campo a API decide pelo dígito verificador do CPF — informe o tipo e a chave é interpretada exatamente como você pretende.

Campos da resposta

keystringopcional
A chave consultada, normalizada pelo DICT.
typestringopcional
cpf, cnpj, email, phone ou evp.
owner_namestringopcional
Nome do titular da conta associada à chave.
owner_documentstringopcional
CPF ou CNPJ do titular, mascarado pelo próprio DICT no caso de pessoa física.
bank_namestring | nullopcional
Nome da instituição do recebedor. Null quando o ISPB não está no catálogo.
bank_ispbstring | nullopcional
ISPB (8 dígitos) da instituição do recebedor.
end_to_end_idstring | nullopcional
Identificador desta consulta. Envie em POST /v1/payouts como end_to_end_id para pagar esta chave. É também o id que a liquidação vai carregar.
expires_atstring | nullopcional
Validade do end_to_end_id (12 horas). Depois disso, consulte a chave de novo.

Se end_to_end_id vier null

Em situações raras a consulta resolve o titular mas não emite o id. Nesse caso o pagamento por pix_key não pode ser feito com essa consulta: repita a chamada para obter um id válido.

Formato da chave é validado antes da consulta

Chave fora do formato é recusada com 422 sem chegar ao Banco Central — consulta inválida custa caro no saldo de consultas da conta. CPF e CNPJ são validados com dígito verificador e o telefone é aceito com ou sem DDI (11999999999 e +5511999999999 resolvem a mesma chave); a máscara é opcional em todos. A resposta traz a chave já canonizada.

Uma consulta por pagamento

O DICT trabalha com um saldo de consultas por conta. Cada consulta gasta uma unidade desse saldo, e o pagamento só a devolve quando reenvia o end_to_end_id daquela consulta. Consultar sem pagar, ou pagar sem reenviar o id, esgota o saldo e passa a rejeitar as consultas seguintes com 429.

Cada end_to_end_id vale um pagamento

O id é de uso único e expira em 12 horas. Depois de usado em um payout, consulte a chave de novo para o próximo pagamento. Não guarde o id para reutilizar, e não faça varredura de chaves: este endpoint aceita 30 requisições por minuto por chave de API (contra 100 do restante), além de uma cota diária por conta. Estourar devolve 429 PIX_DICT_QUOTA_EXCEEDED.
Requisição
curl https://apiv2.onnixpay.com/v1/pix/dict/lookup \
  -H "x-api-key: sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "maria@exemplo.com"
  }'
Resposta
{
  "object": "pix_key_lookup",
  "key": "maria@exemplo.com",
  "type": "email",
  "owner_name": "Maria Souza",
  "owner_document": "***456789**",
  "bank_name": "Banco do Brasil",
  "bank_ispb": "00000000",
  "end_to_end_id": "E1393589320260828143000s0a1b2c3d4",
  "expires_at": "2026-08-29T14:30:00.000Z"
}
AnteriorListar pagamentosPróximo Listar minhas chaves