Comece aqui

Segurança da API


Nesta páginaOnde cada mecanismo entraIP cadastradoAssinatura de callbacksCuidados com a credencial

Proteja a sua integração com os mecanismos que cada produto da PayZu exige.

Onde cada mecanismo entra

MecanismoProdutosComo aparece
Certificado mTLSPayZu Payments e recorrência no cartãoCertificado de cliente emitido pela PayZu, exigido por padrão em todas as rotas de https://api.payzu.io/v1
IdempotênciaPayZu Pix, PayZu Conta Hub, PayZu Gateway e PayZu OnboardingclientReference, externalRef, Idempotency-Key e clientCode
Limites de requisiçãoPayZu Pix, PayZu Conta Hub e PayZu GatewayResposta 429, com o tempo de espera
IP cadastradoPayZu Pix e PayZu Conta Hub403 quando a chamada sai de um IP fora da lista
Assinatura de callbacksPayZu Pix, PayZu Conta Hub, PayZu Payments, PayZu Gateway e PayZu OnboardingHMAC-SHA256 com um segredo que só você e a PayZu conhecem

IP cadastrado

ProdutoDe quem é a listaOnde vale
PayZu PixDa contaTodas as rotas de produção
PayZu Conta HubDa credencialTodas 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ódigoHTTPMensagem
PZA203403Acesso não permitido a partir do endereço de IP 203.0.113.10.
PZA205403Conta com token de saque exige IP cadastrado na whitelist. Cadastre o IP de origem (203.0.113.10) antes de operar.
TOKEN_IP_NOT_ALLOWED403Esta 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.

ItemComo é
CabeçalhoX-Callback-Signature, no formato t=<segundos>, v1=<HMAC em hexadecimal>; só quando há segredo
String assinada<t>.<corpo cru>
SegredoAparece uma única vez, na criação ou na rotação
Resposta e retentativasEm Webhooks e callbacks

Em todos os produtos:

  • Verifique a assinatura antes de processar o evento e responda 2xx só 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_in e 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.