# 查询收款方 (/zh/docs/conta-digital/recipient)

<QuickLinks>
  <QuickLink href="/docs/conta-digital/endpoints/pix/post_pix_destination" title="查询收款方" method="POST" path="/transactions/pix/destination" />

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

  <QuickLink href="/docs/conta-digital/qr-payments" title="支付 Pix 复制粘贴码" />
</QuickLinks>

查询不会移动资金。

## 查询 [#查询]

[`POST /transactions/pix/destination`](/docs/conta-digital/endpoints/pix/post_pix_destination)，作用域 `PIX_DICT_READ`。在 `pixKey` 中发送一个密钥，或在 `brCode` 中发送一个代码，不能同时发送两者。

<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` 或 `EVP`）是可选的，只能与 `pixKey` 一起发送。对于 11 位数字的密钥，请带上它，因为它可能是 CPF，也可能是手机号。

对于 Pix 复制粘贴码，只发送代码：

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

## 响应 [#响应]

```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
}
```

* 名称为全名。CPF 已脱敏，CNPJ 已格式化；账号只显示最后四位。
* 代码固定金额时会填写 `amount`。对于密钥，始终为 `null`。
* `isVerified: true` 表示名称来自 DICT，即 Pix 的密钥目录。为 `false` 时，名称来自二维码本身：是生成代码的一方写入的内容，未经验证。
* 对于密钥，没有查询就没有响应：拒绝为 `503`。

## 查询次数限制 [#查询次数限制]

每个账户每分钟最多 30 次查询，另有平台上限。超过后，API 返回 `429` `AUTH_TOO_MANY_REQUESTS` 和 `Retry-After`。银行也有自己的限制，此时拒绝为 `503` `PIX_DEST_THROTTLED`。动态码在银行解析，可能因与密钥查询相同的原因被拒绝。

## 拒绝 [#拒绝]

以下拒绝可以在等待后重试：

| 状态  | `code`                   | 何时                           |
| --- | ------------------------ | ---------------------------- |
| 429 | `AUTH_TOO_MANY_REQUESTS` | 超过了查询次数限制。请等待 `Retry-After`。 |
| 503 | `PIX_DEST_THROTTLED`     | 超过了银行的限制。                    |
| 503 | `PIX_DEST_UNAVAILABLE`   | 查询未进行。                       |
| 503 | `RATE_LIMIT_UNAVAILABLE` | 请求次数限制的控制服务不可用；没有执行任何操作。     |

其他拒绝重试也不会改变。来自请求或目的地的拒绝：

| 状态  | `code`                               | 何时                                              |
| --- | ------------------------------------ | ----------------------------------------------- |
| 400 | `SCHEMA_INVALID`                     | 两个字段都没有、两个同时出现，或 `pixKeyType` 与 `brCode` 一起出现。  |
| 400 | `WITHDRAW_INVALID_PIX_KEY`           | CPF 或 CNPJ 校验位错误，或 11 位数字既不是 CPF 也不是手机号。        |
| 400 | `WITHDRAW_PIX_KEY_TYPE_MISMATCH`     | `pixKeyType` 与密钥不符。`details.inferred` 给出推断出的类型。 |
| 400 | `QR_CRC`、`QR_MALFORMED`、`QR_NOT_PIX` | 代码已损坏、格式无效或不是 Pix 代码。                           |
| 404 | `PIX_DEST_PIX_KEY`                   | 该密钥在 DICT 中不存在。                                 |
| 422 | `WITHDRAW_UNRECOGNIZED_PIX_KEY`      | 无法推断密钥类型。                                       |

与账户相关的拒绝见[查询收款方](/docs/conta-digital/endpoints/pix/post_pix_destination)，凭证和作用域相关的拒绝见[身份认证](/docs/conta-digital/authentication#凭证拒绝)。