Comece aquiSegurança da API

Certificado mTLS


Nesta páginaQuem precisaComo funcionaEnvie o certificadoGuarde o certificadoErros de certificado

Conecte-se às APIs de cartão da PayZu com TLS mútuo, apresentando o certificado de cliente emitido pela PayZu em todas as rotas de https://api.payzu.io/v1, do POST /token em diante.

A credencial exige o certificado por padrão.

Se a sua integração não vai usar certificado, peça à PayZu para desligar a exigência na sua credencial. Com ela desligada, as chamadas vão só com client_id, client_secret e o token.

Quem precisa

O PayZu Gateway, o PayZu Pix, o PayZu Conta Hub e o PayZu Onboarding não usam certificado de cliente.

Como funciona

Fluxo do mTLS: a aplicação abre a conexão com o certificado e a chave, pede o token com a credencial em Basic, chama as demais rotas com o token em Bearer, e a API de cartão confere o certificado

  1. A sua aplicação abre a conexão apresentando o certificado e a chave privada, ou sem eles, se a exigência estiver desligada na credencial.
  2. No POST /token, client_id e client_secret vão em Basic sobre essa conexão.
  3. Nas demais rotas, o token vai em Authorization: Bearer, e o certificado continua na conexão.
  4. A API confere o certificado contra a credencial do Basic ou do token. Sem certificado, a chamada só passa com a exigência desligada.

Envie o certificado

Guarde o certificado

  • Trate a chave privada como segredo: fora do repositório, fora do navegador, com acesso restrito ao processo que chama a API.
  • Acompanhe a data de expiração do certificado e troque-o antes de vencer.
  • Carregue sempre o certificado e a chave privada do mesmo par.

Erros de certificado

CódigoHTTPMensagem
-401Não foi possível verificar o certificado.
-401Certificado não pertence ao usuário autenticado.

A primeira mensagem vale, com a exigência ligada, para a chamada sem certificado ou com certificado não aceito. Um certificado vencido ou não emitido pela PayZu não passa na validação e conta como ausente.

A segunda é a do certificado de outra credencial: o certificado apresentado precisa ser o da credencial, com a exigência ligada ou desligada.

Se a chamada falhar, confira nesta ordem:

O que conferirComo
Certificado e chaveSe a credencial exige o certificado, os dois arquivos PEM são do mesmo par, estão dentro da validade e foram carregados na conexão
TokenAinda não passou o expires_in do POST /token; se passou, peça outro
HeaderAuthorization: Basic só no POST /token; nas demais rotas, Authorization: Bearer

As outras mensagens estão em Erros do PayZu Payments, e a lista inteira, no Catálogo de erros.