PayZu Conta Hub

Autenticação


Nesta páginaObtenha o tokenEnvie o token em cada chamadaValidade e renovaçãoErros de autenticaçãoIP de origem

Troque 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, com client_id:client_secret em base64;
  • no corpo, nos campos client_id e client_secret, em application/x-www-form-urlencoded ou em JSON.

Se o cabeçalho e o corpo vierem juntos, vale o cabeçalho.

bash
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"
  }'

Referência: Gerar um token de acesso

Envie o token em cada chamada

bash
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ódigoHTTPMensagem
TOKEN_UNSUPPORTED_GRANT_TYPE400grant_type não suportado. Use client_credentials.
TOKEN_INVALID401Credencial de integração inválida.
TOKEN_IP_NOT_ALLOWED403Esta credencial não pode ser usada a partir deste IP.
TOKEN_MISSING_SCOPE403Esta credencial não tem permissão para esta operação.
AUTH_TOO_MANY_REQUESTS429Muitas 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.