Autenticação
Autentique cada chamada na forma que o seu produto exige.
Formas de autenticar
| Forma | Produtos | Onde vai | Validade |
|---|---|---|---|
| Token Bearer da conta | PayZu Pix | Authorization: Bearer <token> | Sem troca; no sandbox, a credencial vale 24 horas |
| Credencial trocada por token | PayZu Conta Hub | Authorization: Bearer <access_token> | 15 minutos (expires_in: 900) |
| Certificado mTLS com token | PayZu Payments e recorrência no cartão | Certificado na conexão e Authorization: Bearer <access_token> | expires_in, em segundos |
| Chave de checkout | Checkout e token de cartão do PayZu Gateway | Header x-checkout-key | Sem troca de token |
| Chave de API | PayZu Gateway | Authorization: Bearer <chave>, só a partir do seu servidor | Sem troca de token |
| Chave de API | PayZu Câmbio | Authorization: Bearer <chave> | Sem troca de token; a chave vence na data de expiresAt |
| Conta de serviço com troca de token | PayZu Onboarding | Authorization: Bearer <access_token> | expires_in, em segundos: o menor entre o prazo configurado e o que resta do ID token |
A chave de checkout vai em POST /v1/card-tokens e nas rotas de plano e de assinatura do checkout. As rotas de fatura e de link do checkout não pedem chave.
Peça o token
Envie client_id e client_secret em POST /oauth/token, em Authorization: Basic ou no corpo. O token da credencial também vale direto no Bearer.
Envie client_id e client_secret em Basic só no POST /token, com o certificado na conexão. A recorrência no cartão usa o mesmo token.
Envie o ID token da sua conta de serviço no corpo de POST /oauth/token, sem o header Authorization.
| Produto | Regra da troca |
|---|---|
| PayZu Conta Hub | O corpo vai em JSON ou em application/x-www-form-urlencoded. A lista de IPs da credencial vale nesta rota também. |
| PayZu Payments | O certificado vai em toda conexão, a menos que a PayZu desligue a exigência na credencial. |
| PayZu Onboarding | A PayZu cadastra uma autorização para a sua conta de serviço. Quando ela revoga a autorização, os tokens emitidos por ela deixam de valer na hora. |
Renove o token antes de expires_in e mantenha-o fora do navegador.
No PayZu Conta Hub, a troca de token tem cota própria por client_id e por IP: peça um token por processo e reutilize-o pelos 15 minutos de validade.
Erros de autenticação
| Código | HTTP | Mensagem |
|---|---|---|
PZA100 | 401 | Unauthorized |
PZA200 | 403 | Forbidden |
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. |
PZA206 | 403 | Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações. |
| Código | HTTP | Mensagem |
|---|---|---|
TOKEN_UNSUPPORTED_GRANT_TYPE | 400 | grant_type não suportado. Use client_credentials. |
TOKEN_INVALID | 401 | Credencial de integração inválida. |
TOKEN_IP_NOT_ALLOWED | 403 | Esta credencial não pode ser usada a partir deste IP. |
TOKEN_MISSING_SCOPE | 403 | Esta credencial não tem permissão para esta operação. |
AUTH_TOO_MANY_REQUESTS | 429 | Muitas tentativas. Tente novamente em alguns minutos. |
Valem também para a recorrência no cartão.
| Código | HTTP | Mensagem |
|---|---|---|
| - | 400 | Basic token não definido. |
| - | 400 | grant_type não informado |
| - | 400 | grant type não suportado |
| - | 401 | Unauthorized |
| - | 401 | Não foi possível verificar o certificado. |
| - | 401 | Certificado não pertence ao usuário autenticado. |
| - | 401 | Token inválido ou expirado. |
| - | 403 | Não foi possível concluir sua solicitação |
| Código | HTTP | Mensagem |
|---|---|---|
invalid_grant | 400 | subject_token recusado (assinatura, emissor, audiência, prazo) ou identidade sem grant nesta audience. |
invalid_request | 400 | Corpo fora do formato, campo desconhecido ou header Authorization presente. |
invalid_target | 400 | audience inexistente ou desativada. |
unsupported_grant_type | 400 | grant_type diferente de token-exchange. |
audience_not_resolved | 401 | Não foi possível identificar o tenant da credencial. |
invalid_token | 401 | Token inválido, expirado ou emitido para outro serviço. |
missing_bearer | 401 | Credencial ausente. Envie o header Authorization com Bearer. |
audience_disabled | 403 | Tenant desativado. Nenhuma credencial dele é aceita. |
Os códigos do PayZu Câmbio estão em Autenticação do produto, e a lista inteira, no Catálogo de erros.