Segurança da API
Proteja a sua integração com os mecanismos que cada produto da PayZu exige.
Onde cada mecanismo entra
| Mecanismo | Produtos | Como aparece |
|---|---|---|
| Certificado mTLS | PayZu Payments e recorrência no cartão | Certificado de cliente emitido pela PayZu, exigido por padrão em todas as rotas de https://api.payzu.io/v1 |
| Idempotência | PayZu Pix, PayZu Conta Hub, PayZu Gateway e PayZu Onboarding | clientReference, externalRef, Idempotency-Key e clientCode |
| Limites de requisição | PayZu Pix, PayZu Conta Hub e PayZu Gateway | Resposta 429, com o tempo de espera |
| IP cadastrado | PayZu Pix e PayZu Conta Hub | 403 quando a chamada sai de um IP fora da lista |
| Assinatura de callbacks | PayZu Pix, PayZu Conta Hub, PayZu Payments, PayZu Gateway e PayZu Onboarding | HMAC-SHA256 com um segredo que só você e a PayZu conhecem |
Nas APIs de cartão e no checkout do PayZu Gateway não há deduplicação: consulte antes de repetir.
Certificado mTLSA PayZu pode desligar a exigência do certificado na credencial.
Limites de requisiçãoA espera vem no corpo, no header Retry-After ou, no PayZu Gateway, só na mensagem.
IP cadastrado
| Produto | De quem é a lista | Onde vale |
|---|---|---|
| PayZu Pix | Da conta | Todas as rotas de produção |
| PayZu Conta Hub | Da credencial | Todas as rotas autenticadas, inclusive a troca de token |
No PayZu Pix, a conta que envia Pix pela API sem nenhum IP cadastrado é recusada em qualquer rota. Onde cadastrar: IP cadastrado no PayZu Pix.
| Código | HTTP | Mensagem |
|---|---|---|
PZA203 | 403 | Acesso não permitido a partir do endereço de IP 203.0.113.10. |
PZA205 | 403 | Conta com token de saque exige IP cadastrado na whitelist. Cadastre o IP de origem (203.0.113.10) antes de operar. |
TOKEN_IP_NOT_ALLOWED | 403 | Esta credencial não pode ser usada a partir deste IP. |
Fixe o IP de saída antes de cadastrá-lo.
Saídas por proxy, NAT ou nuvem com IP dinâmico mudam o endereço de origem.
Assinatura de callbacks
A assinatura é um HMAC-SHA256 do carimbo de tempo mais o corpo cru; no PayZu Payments e no PayZu Gateway, também de um nonce.
| Item | Como é |
|---|---|
| Cabeçalho | X-Callback-Signature, no formato t=<segundos>, v1=<HMAC em hexadecimal>; só quando há segredo |
| String assinada | <t>.<corpo cru> |
| Segredo | Aparece uma única vez, na criação ou na rotação |
| Resposta e retentativas | Em Webhooks e callbacks |
| Item | Como é |
|---|---|
| Cabeçalho | X-Payzu-Signature, com sha256= mais o HMAC em hexadecimal, e X-Payzu-Timestamp, em milissegundos |
| String assinada | <X-Payzu-Timestamp>.<corpo cru> |
| Segredo | Aparece uma única vez, na criação ou na rotação |
| Resposta e retentativas | Qualquer 2xx em até 10 segundos; sem ele, nova tentativa com o mesmo X-Payzu-Delivery |
Detalhes em Webhooks.
| Item | Como é |
|---|---|
| Cabeçalho | X-Webhook-Signature, com o HMAC em hexadecimal, X-Webhook-Timestamp, em milissegundos, e X-Webhook-Nonce |
| String assinada | <timestamp>.<nonce>.<corpo cru> |
| Segredo | Vem com a credencial |
| Resposta e retentativas | Qualquer 2xx em até 5 segundos; retentativas em Webhooks |
| Item | Como é |
|---|---|
| Cabeçalho | X-Webhook-Signature, com o HMAC em hexadecimal, X-Webhook-Timestamp, em milissegundos, e X-Webhook-Nonce |
| String assinada | <timestamp>.<nonce>.<corpo cru> |
| Segredo | Vem em secret, no cadastro de cada webhook e na troca do segredo |
| Resposta e retentativas | Qualquer 2xx em até 5 segundos; retentativas em Webhooks |
Detalhes em Assinatura dos webhooks.
| Item | Como é |
|---|---|
| Cabeçalho | X-Callback-Signature, com sha256= mais o HMAC em hexadecimal, e X-Callback-Timestamp, em segundos |
| String assinada | <X-Callback-Timestamp>.<corpo cru> |
| Segredo | Provisionado pela PayZu |
| Resposta e retentativas | Sem 2xx, nova tentativa em 1, 5, 30, 120 e 480 minutos; redirecionamento nunca é seguido |
Detalhes em Callbacks.
Em todos os produtos:
- Verifique a assinatura antes de processar o evento e responda
2xxsó depois de gravar o que precisa. - Guarde o segredo no servidor, numa variável de ambiente ou num gerenciador de segredos, nunca no código.
- Calcule o HMAC sobre o corpo exatamente como chegou e compare em tempo constante.
- O mesmo evento pode chegar mais de uma vez. Grave o que já processou e ignore a repetição; o identificador de cada produto está na página de webhooks dele.
Cuidados com a credencial
- Mande o token só pelo header
Authorization, nunca na URL. - Renove o token antes de
expires_ine troque a credencial pelo painel se ela vazar. No Servidor MCP, trocar o token da API corta todos os clientes conectados na próxima chamada. - Nunca exponha
client_secret, certificado, segredo de callback ou a chave de API do PayZu Gateway no navegador ou em repositório.
A chave de checkout do PayZu Gateway é a exceção.
Ela é uma chave pública da conta.