PayZu PaymentsSegurança e autenticação

Token


Nesta páginaPeça o tokenValidade e renovaçãoCertificado e credencialErros de autenticação

Troque o client_id e o client_secret da conta por um token em POST /token e envie esse token em toda chamada.

Peça o token

Mande client_id:client_secret em Authorization: Basic, em base64, e grant_type igual a client_credentials no corpo. Nenhum outro valor de grant_type é aceito.

bash
curl --request POST \
  --url 'https://api.sandbox.payzu.dev/v1/token' \
  --user "$PAYZU_CLIENT_ID:$PAYZU_CLIENT_SECRET" \
  --cert "$PAYZU_CLIENT_CERT" --key "$PAYZU_CLIENT_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "grant_type": "client_credentials" }'

Referência: Gerar um token de acesso

Nas rotas de cobrança, envie Authorization: Bearer com o access_token e mantenha o mesmo certificado na conexão.

O exemplo em Node.js usa o pacote undici.

O fetch global do Node.js não recebe certificado de cliente. Com a exigência do certificado desligada na credencial, tire o --cert/--key do cURL e, no Node.js, o Agent, com a leitura dos arquivos PEM, e o dispatcher.

Validade e renovação

A validade vem em expires_in, em segundos. Programe a renovação pelo valor recebido, não por um número fixo: peça um token por processo, reutilize-o e peça outro pouco antes de vencer.

Certificado e credencial

  • Padrão: a credencial exige o certificado de cliente na conexão, já no POST /token.
  • Exigência desligada: a PayZu pode desligar a exigência na sua credencial, e aí o POST /token e as rotas aceitam a chamada sem certificado.
  • Dono do certificado: o certificado é emitido para a sua credencial, e o nome (CN) dele é o próprio client_id. Se a chamada apresenta um certificado, com a exigência ligada ou desligada, o client_id do Basic ou do token precisa ser o mesmo dele.
  • Validade: 365 dias a partir da emissão.
  • IP de origem: o PayZu Payments não confere. Quem identifica a sua aplicação é o token e, quando a credencial exige, o certificado.

Como enviar o certificado no cURL, no Node.js e em outras linguagens está em Certificado mTLS.

Erros de autenticação

Os erros de autenticação ainda saem sem code; decida pelo status e pela mensagem.

CódigoHTTPMensagem
-400Basic token não definido.
-400grant_type não informado
-400grant type não suportado
-401Unauthorized
-401Não foi possível verificar o certificado.
-401Certificado não pertence ao usuário autenticado.
-401Token inválido ou expirado.
-403Não foi possível concluir sua solicitação

Todos os códigos do PayZu Payments estão no Catálogo de erros.