Autenticação

A autenticação da API Cartão acontece em duas camadas que trabalham juntas:

1. Mutual TLS (mTLS): toda conexão com a API usa um certificado de cliente emitido pela PayZu, garantindo a identidade tanto do servidor quanto do cliente durante a comunicação.
2. Token JWT: sobre a conexão mTLS, você obtém um access_token via POST /token e o envia no header Authorization: Bearer em todas as demais rotas.

Ambientes

Mutual TLS

Antes de qualquer chamada, instale o certificado de cliente fornecido pela equipe PayZu e configure seu sistema para utilizá-lo em todas as chamadas à API, sempre por HTTPS.

No curl, o certificado entra pelas flags --cert (certificado do cliente), --key (chave privada) e --cacert (cadeia da autoridade certificadora):

curl --request GET \
     --url https://api.sandbox.payzu.io/v1/charges \
     --header 'accept: application/json' \
     --cert cliente.crt \
     --key cliente.key \
     --cacert ca.pem

Obter o token

A rota POST /token retorna um token JWT para autenticação das rotas. Ela usa Basic Auth (seu client_id como usuário e client_secret como senha), sempre sobre a conexão mTLS, e recebe o grant_type client_credentials no corpo:

curl --request POST \
     --url https://api.sandbox.payzu.io/v1/token \
     --user "$CLIENT_ID:$CLIENT_SECRET" \
     --header 'content-type: application/json' \
     --cert cliente.crt \
     --key cliente.key \
     --cacert ca.pem \
     --data '{ "grant_type": "client_credentials" }'

Em produção, troque a base URL para https://api.payzu.io/v1.

A resposta traz o token e o tempo de expiração:

{
  "access_token": "string",
  "token_type": "string",
  "expires_in": 0
}

Chamadas autenticadas

Depois de obter o token, toda rota da API recebe o header Authorization: Bearer, sempre sobre a mesma configuração de mTLS:

curl --request GET \
     --url https://api.sandbox.payzu.io/v1/charges \
     --header 'accept: application/json' \
     --header "Authorization: Bearer $ACCESS_TOKEN" \
     --cert cliente.crt \
     --key cliente.key \
     --cacert ca.pem

Próximos passos