# Consultar chave Pix (/docs/pix-processamento/endpoints/keys-and-dict/get_pix_key)

## GET /pix/key

`GET https://api.payzu.processamento.com/v1/pix/key`

Consulta o DICT (Diretório de Identificadores de Contas Transacionais) para obter informações sobre uma chave Pix antes de enviar um pagamento. Retorna os dados do titular da chave e a instituição financeira associada. Permissão do token: `DEPOSIT` ou `WITHDRAW`.

Guia: Receber pagamento Pix (/docs/pix-processamento/tutoriais/receive-pix)

### Query params

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `pixKey` | string | yes | A chave Pix a consultar (CPF, CNPJ, email, telefone ou EVP). — minLength: 1; maxLength: 77 |

### Responses

**200** Chave Pix encontrada

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `pixKey` | string | no | A chave Pix que foi consultada. |
| `document` | string | no | CPF ou CNPJ do titular (parcialmente mascarado por privacidade). |
| `name` | string | no | Nome do titular da chave Pix. |
| `branch` | string | no | Número da agência bancária (mascarado). |
| `accountNumber` | string | no | Número da conta (mascarado). |
| `personType` | string | no | Tipo de pessoa: PF, PJ ou vazio quando não informado. — `PF`, `PJ`, `` |
| `accountType` | string | no | Tipo de conta devolvido pelo DICT, como CACC, SVGS, TRAN ou SLRY. |
| `institutionIspb` | string | no | Código ISPB da instituição financeira. |
| `institutionCode` | string | no | Código COMPE da instituição financeira. |
| `institutionName` | string | no | Nome da instituição financeira. |

**400** Formato de chave Pix inválido

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |

**401** Falha de autenticação

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |

**403** Operação não permitida

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |

**404** Chave Pix não encontrada no DICT

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |

**422** Operação recusada

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |

**424** Falha na instituição financeira

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |

**429** Limite de requisições excedido

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |

**500** Erro interno

| Field | Type | Required | Details |
| --- | --- | --- | --- |
| `status` | string | yes | Marcador fixo de resposta de erro. |
| `error` | string | yes | Nome do status HTTP correspondente. |
| `errorCode` | string | yes | Código de erro estável e legível por máquina, quando disponível. |
| `message` | string | yes | Mensagem de erro legível. |
| `statusCode` | integer | yes | Código de status HTTP. |
| `requestId` | string | yes | ID único de correlação da requisição (cuid). |
| `details` | object[] | no | Erros de validação por campo, quando aplicável. |
| `details.field` | string | yes | Caminho do campo rejeitado na validação, sem a barra inicial. |
| `details.message` | string | yes | Motivo da rejeição daquele campo, em português. |
| `retryAfterSeconds` | integer | no | Segundos a aguardar antes de tentar novamente. |