# Consultar destinatário (/docs/conta-digital/recipient)

<QuickLinks>
  <QuickLink href="/docs/conta-digital/endpoints/pix/post_pix_destination" title="Consultar destinatário" method="POST" path="/transactions/pix/destination" />

  <QuickLink href="/docs/conta-digital/withdrawals" title="Saques Pix" />

  <QuickLink href="/docs/conta-digital/qr-payments" title="Pagar Pix copia e cola" />
</QuickLinks>

A consulta não move dinheiro.

## Consultar [#consultar]

[`POST /transactions/pix/destination`](/docs/conta-digital/endpoints/pix/post_pix_destination), escopo `PIX_DICT_READ`. Mande uma chave em `pixKey` ou um código em `brCode`, nunca os dois.

<Tabs items="['curl', 'Node.js']">
  <Tab value="curl">
    ```bash
    curl -X POST https://api.hub.payzu.com.br/api/v1/transactions/pix/destination \
      -H "Authorization: Bearer $PAYZU_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{ "pixKey": "52998224725", "pixKeyType": "CPF" }'
    ```
  </Tab>

  <Tab value="Node.js">
    ```ts
    const res = await fetch('https://api.hub.payzu.com.br/api/v1/transactions/pix/destination', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.PAYZU_TOKEN}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ pixKey: '52998224725', pixKeyType: 'CPF' }),
    });
    const destinatario = await res.json();
    ```
  </Tab>
</Tabs>

`pixKeyType` (`CPF`, `CNPJ`, `EMAIL`, `PHONE` ou `EVP`) é opcional e só vai com `pixKey`. Mande-o com chaves de 11 dígitos, que podem ser CPF ou celular.

Para um Pix copia e cola, mande só o código:

```json
{ "brCode": "00020126400014br.gov.bcb.pix0118fulano@exemplo.com..." }
```

## Resposta [#resposta]

```json
{
  "source": "PIX_KEY",
  "pixKey": "***.982.247-**",
  "pixKeyType": "CPF",
  "holder": { "name": "Maria Aparecida Souza", "document": "***.982.247-**" },
  "bank": { "name": "Banco Exemplo S.A.", "ispb": "99999999", "branch": "0001", "accountNumber": "****7788" },
  "amount": null,
  "isAmountFixed": false,
  "isVerified": true
}
```

* O nome vem por extenso. O CPF vem mascarado e o CNPJ, formatado; a conta, só com os quatro últimos dígitos visíveis.
* `amount` vem preenchido quando o código fixa valor. Para chave, é sempre `null`.
* `isVerified: true` quer dizer que o nome veio do DICT, o diretório de chaves do Pix. Com `false`, o nome veio do próprio QR Code: é o que quem gerou o código escreveu, sem verificação.
* Para uma chave, sem consulta não há resposta: a recusa é `503`.

## Limite de consultas [#limite-de-consultas]

Até 30 consultas por minuto por conta, além de um teto da plataforma. Acima disso, a API responde `429` `AUTH_TOO_MANY_REQUESTS` com `Retry-After`. O banco também tem limite próprio, e a recusa então é `503` `PIX_DEST_THROTTLED`. Código dinâmico é resolvido no banco e pode ser recusado pelos mesmos motivos de uma consulta de chave.

## Recusas [#recusas]

Vale repetir estas, depois de esperar:

| Status | `code`                   | Quando                                                               |
| ------ | ------------------------ | -------------------------------------------------------------------- |
| 429    | `AUTH_TOO_MANY_REQUESTS` | Passou do limite de consultas. Espere o `Retry-After`.               |
| 503    | `PIX_DEST_THROTTLED`     | Passou do limite do banco.                                           |
| 503    | `PIX_DEST_UNAVAILABLE`   | A consulta não aconteceu.                                            |
| 503    | `RATE_LIMIT_UNAVAILABLE` | O controle do limite de requisições está fora do ar; nada foi feito. |

As demais não mudam com a repetição. As que vêm do pedido ou do destino:

| Status | `code`                                 | Quando                                                                     |
| ------ | -------------------------------------- | -------------------------------------------------------------------------- |
| 400    | `SCHEMA_INVALID`                       | Nenhum dos dois campos, os dois juntos, ou `pixKeyType` com `brCode`.      |
| 400    | `WITHDRAW_INVALID_PIX_KEY`             | CPF ou CNPJ com dígito errado, ou 11 dígitos que não são CPF nem celular.  |
| 400    | `WITHDRAW_PIX_KEY_TYPE_MISMATCH`       | `pixKeyType` não bate com a chave. `details.inferred` diz o tipo deduzido. |
| 400    | `QR_CRC`, `QR_MALFORMED`, `QR_NOT_PIX` | O código está corrompido, fora do formato ou não é de Pix.                 |
| 404    | `PIX_DEST_PIX_KEY`                     | A chave não existe no DICT.                                                |
| 422    | `WITHDRAW_UNRECOGNIZED_PIX_KEY`        | Não dá para deduzir o tipo da chave.                                       |

As recusas ligadas à conta estão em [Consultar destinatário](/docs/conta-digital/endpoints/pix/post_pix_destination), e as de credencial e escopo, em [Autenticação](/docs/conta-digital/authentication#recusas-de-credencial).