Consultar o recebedor
Mostre ao usuário quem vai receber antes de confirmar um Pix, com o nome do titular e a instituição que o DICT informa para a chave ou para o código copia e cola.
Consulte uma chave
Envie pixKey e, quando souber, pixKeyType. Sem o tipo, a API deduz pelo formato, e uma chave de 11 dígitos pode ser lida como CPF ou como celular. A consulta não paga nem reserva nada.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/pix/destination' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{ "pixKey": "52998224725", "pixKeyType": "CPF" }'{
"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
}Referência: Consultar o recebedor de uma chave ou QR Code
| Campo | Como vem |
|---|---|
holder.name, bank.name | O que mostrar ao usuário. |
pixKey | Mascarada quando é CPF, e-mail ou telefone. Para pagar, use a chave que você já tem. |
holder.document | O CPF aparece só com os dígitos do meio. |
accountNumber | Só os quatro últimos dígitos. |
amount | Sempre null numa chave. |
Consulte um copia e cola
Envie o código inteiro em brCode, sem pixKey nem pixKeyType: a rota aceita a chave ou o código, nunca os dois. Na resposta, source vem BR_CODE, e amount e isAmountFixed mostram o valor que o código fixa.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/transactions/pix/destination' \
--header 'Authorization: Bearer SEU_TOKEN' \
--header 'Content-Type: application/json' \
--data '{ "brCode": "00020126400014br.gov.bcb.pix0118fulano@exemplo.com520400005303986540525.005802BR5913FULANO DE TAL6009SAO PAULO62140510PEDIDO482163048572" }'{
"source": "BR_CODE",
"pixKey": "f***@exemplo.com",
"pixKeyType": "EMAIL",
"holder": {
"name": "Fulano de Tal",
"document": "***.456.789-**"
},
"bank": { "name": "Banco Exemplo S.A.", "ispb": "99999999" },
"branch": "0001",
"accountNumber": "****4321",
"amount": 2500,
"isAmountFixed": true,
"isVerified": true
}No código dinâmico, o valor pode mudar depois da consulta.
Ele vem do banco de quem cobrou. No pagamento, mande o valor que o usuário conferiu, como em Pagar um Pix copia e cola.
Com isVerified true, o nome do titular veio do DICT.
Com false, veio do texto do código, escrito por quem o gerou. No código estático, isso acontece quando a consulta ao DICT está indisponível, e a resposta sai assim em vez de falhar.
Erros desta operação
| Código | HTTP | Mensagem |
|---|---|---|
QR_CRC | 400 | O código PIX está corrompido — copie novamente do recebedor. |
QR_MALFORMED | 400 | Este código PIX não está num formato válido. |
QR_NOT_PIX | 400 | Este código não é um QR code de PIX. |
WITHDRAW_INVALID_PIX_KEY | 400 | A chave PIX é inválida: CPF ou CNPJ com dígito verificador errado, ou 11 dígitos que não são CPF nem celular com DDD. |
WITHDRAW_PIX_KEY_TYPE_MISMATCH | 400 | O tipo informado não corresponde ao formato da chave PIX. |
PIX_DEST_PIX_KEY | 404 | Não encontramos essa chave PIX. Confira se ela está correta. |
WITHDRAW_UNRECOGNIZED_PIX_KEY | 422 | A chave PIX informada não corresponde a nenhum formato válido. |
PIX_DEST_NOT_AUTHORIZED_AT_PROVIDER | 502 | A consulta de chaves PIX não está autorizada para esta conta. Fale com o suporte — tentar de novo não resolve. |
PIX_DEST_THROTTLED | 503 | Muitas consultas de chave em pouco tempo. Aguarde um momento e tente de novo. |
PIX_DEST_UNAVAILABLE | 503 | A consulta de chaves PIX está indisponível no momento. Tente de novo em instantes. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.