Segurança
Veja o que protege a credencial e os webhooks e quais dados de terceiros a API mascara nas respostas.
Credencial
| Controle | Como funciona |
|---|---|
| Conta | A credencial opera só a conta dela. Nenhuma rota recebe accountId. |
| Segredo | O client_secret aparece uma vez, na criação. A PayZu guarda só o hash dele. |
| Último uso | A PayZu registra o último uso de cada credencial. |
Escopos, lista de IPs, rotação e revogação: Autenticação.
Segredo errado e client_id inexistente recebem a mesma resposta, 401 com TOKEN_INVALID.
Segredos dos webhooks
Cada webhook chega assinado. O segredo depende de para onde ele vai:
| Segredo | Começa com | Assina o que vai para | Como obter e trocar |
|---|---|---|---|
| Do endpoint | whsec_ | O endpoint cadastrado | Vem só na resposta de POST /transactions/webhooks. Para trocar, gere outro no painel, com o PIN. O anterior para de valer na hora. |
| De callback | cbsec_ | A callbackUrl informada na operação | Vem uma vez, em POST /transactions/callback-secret. POST /transactions/callback-secret/rotate gera outro, e o anterior para de valer na hora. |
A assinatura vem em X-Payzu-Signature: é o HMAC-SHA256 de <X-Payzu-Timestamp>.<corpo cru>. O timestamp está em milissegundos e muda a cada tentativa. Como conferir: Webhooks.
Uma operação com callbackUrl numa conta sem segredo de callback é recusada com 412 e CALLBACK_SECRET_MISSING.
Dados de terceiros nas respostas
| Dado | Como aparece |
|---|---|
| Chave de destino de saque e de pagamento de Pix copia e cola, na consulta, na listagem e no extrato | Mascarada quando é CPF, e-mail ou telefone. CNPJ e chave aleatória aparecem inteiros. |
| Documento de quem pagou um Pix recebido sem cobrança | CPF mascarado ou CNPJ formatado. |
| Titular na consulta de destinatário | Nome completo, CPF mascarado e só os quatro últimos dígitos da conta. |
ipAddress enviado na cobrança | Não volta em nenhuma resposta nem webhook. |
| Recurso de outra conta | 404, igual ao de um recurso que não existe. |