Autenticação
Nesta página
Obtenha o tokenEnvie o token em cada chamadaValidade e renovaçãoErros de autenticaçãoIP de origemTroque a credencial da conta por um token de acesso de 15 minutos e use-o em todas as chamadas às rotas de /transactions.
Obtenha o token
Chame Gerar um token de acesso com grant_type=client_credentials. A credencial pode ir de duas formas:
- no cabeçalho
Authorization: Basic, comclient_id:client_secretem base64; - no corpo, nos campos
client_ideclient_secret, emapplication/x-www-form-urlencodedou em JSON.
Se o cabeçalho e o corpo vierem juntos, vale o cabeçalho.
curl --request POST \
--url 'https://api.sandbox.payzu.dev/api/v1/oauth/token' \
--header 'Content-Type: application/json' \
--data '{
"grant_type": "client_credentials",
"client_id": "SEU_CLIENT_ID",
"client_secret": "SEU_CLIENT_SECRET"
}'{
"access_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIn0..mQ3Zy1hbVhpbXBsZQ.ZXhlbXBsbw.c2lnbmF0dXJl",
"token_type": "Bearer",
"expires_in": 900
}Referência: Gerar um token de acesso
Envie o token em cada chamada
curl --url 'https://api.sandbox.payzu.dev/api/v1/transactions/balance' \
--header 'Authorization: Bearer SEU_TOKEN'O token_type é sempre Bearer. As operações acontecem na conta da credencial que gerou o token, e nenhuma rota recebe um identificador de conta. Só Consultar o status do serviço dispensa o token.
Validade e renovação
O token vale expires_in segundos (900, ou 15 minutos). Guarde o token com o instante em que o recebeu, use-o em todas as chamadas desse intervalo e peça outro quando estiver perto de vencer. Um token por chamada esgota a cota da troca, que é contada por client_id e por IP.
Diante de um 401, peça um token novo e refaça a chamada uma vez.
Se a própria troca responder 401, revise client_id e client_secret.
Erros de autenticação
| 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. |
Todos os códigos do PayZu Conta Hub estão no Catálogo de erros.
IP de origem
Quando a credencial tem lista de IPs, a API só aceita chamadas que saiam desses endereços, inclusive a troca do token.