查询收款方

查询不会移动资金。

查询

POST /transactions/pix/destination，作用域 PIX_DICT_READ。在 pixKey 中发送一个密钥，或在 brCode 中发送一个代码，不能同时发送两者。

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" }'

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();

pixKeyType（CPF、CNPJ、EMAIL、PHONE 或 EVP）是可选的，只能与 pixKey 一起发送。对于 11 位数字的密钥，请带上它，因为它可能是 CPF，也可能是手机号。

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

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

响应

{
  "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。动态码在银行解析，可能因与密钥查询相同的原因被拒绝。

拒绝

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

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

与账户相关的拒绝见查询收款方，凭证和作用域相关的拒绝见身份认证。