Consultar destinatário

A consulta não move dinheiro.

Consultar

POST /transactions/pix/destination, escopo PIX_DICT_READ. Mande uma chave em pixKey ou um código em brCode, nunca os dois.

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 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:

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

Resposta

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

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

Vale repetir estas, depois de esperar:

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

As recusas ligadas à conta estão em Consultar destinatário, e as de credencial e escopo, em Autenticação.