Look up recipient

The lookup does not move money.

Look up

POST /transactions/pix/destination, scope PIX_DICT_READ. Send a key in pixKey or a code in brCode, never both.

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 or EVP) is optional and only goes with pixKey. Send it with 11-digit keys, which can be a CPF or a mobile number.

For a Pix copy-and-paste code, send only the code:

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

Response

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

• The name comes in full. The CPF comes masked and the CNPJ formatted; the account number shows only its last four digits.
• amount is filled in when the code sets an amount. For a key, it is always null.
• isVerified: true means the name came from the DICT, the Pix key directory. With false, the name came from the QR code itself: it is what the code's creator wrote, without verification.
• For a key, if the lookup does not happen there is no response: the rejection is 503.

Lookup limit

Up to 30 lookups per minute per account, plus a platform cap. Above that, the API responds 429 AUTH_TOO_MANY_REQUESTS with Retry-After. The bank also has its own limit, and the rejection is then 503 PIX_DEST_THROTTLED. A dynamic code is resolved at the bank and can be refused for the same reasons as a key lookup.

Rejections

These are worth repeating, after waiting:

The others do not change when repeated. Those caused by the request or the destination:

Account-related rejections are in Look up recipient, and credential and scope rejections are in Authentication.