PayZu Onboarding

Autenticação


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

Autentique cada chamada com o token de acesso que você obtém trocando o ID token Google da sua conta de serviço, exigido em toda rota menos Gerar um token de acesso.

Obtenha o token

Não há segredo compartilhado: a troca depende da autorização que a PayZu cadastra para a sua conta de serviço no seu tenant.

  • subject_token: o ID token da conta de serviço, emitido para a audiência que a PayZu informou.
  • audience: o id do seu tenant.
  • Corpo: JSON ou application/x-www-form-urlencoded, sem o cabeçalho Authorization.
bash
curl --request POST \
  --url 'https://api.sandbox.payzu.dev/oauth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
    "subject_token": "eyJhbGciOiJSUzI1NiIs...",
    "audience": "payzu"
  }'

Referência: Gerar um token de acesso

Envie o token em cada chamada

bash
curl --url 'https://api.sandbox.payzu.dev/v1/proposals' \
  --header 'Authorization: Bearer SEU_TOKEN'

O tenant vem do token, e nenhuma rota autenticada recebe identificador de tenant. Um recurso de outro tenant responde como inexistente.

Validade e renovação

O token vale expires_in segundos. Reaproveite o mesmo token enquanto ele vale e faça uma troca nova pouco antes do fim.

Um ID token perto de vencer gera um token curto.

O prazo é o menor entre o configurado pela PayZu e o tempo que resta ao ID token enviado.

Se a PayZu revogar a autorização da conta de serviço, os tokens dela param na hora.

Se o 401 voltar depois de uma troca nova, confira a conta de serviço e a autorização com a PayZu.

Erros de autenticação

A troca do token responde no formato { "error", "error_description" }. As demais rotas respondem application/problem+json, com o código em code.

CódigoHTTPMensagem
invalid_grant400subject_token recusado (assinatura, emissor, audiência, prazo) ou identidade sem grant nesta audience.
invalid_request400Corpo fora do formato, campo desconhecido ou header Authorization presente.
invalid_target400audience inexistente ou desativada.
unsupported_grant_type400grant_type diferente de token-exchange.
audience_not_resolved401Não foi possível identificar o tenant da credencial.
invalid_token401Token inválido, expirado ou emitido para outro serviço.
missing_bearer401Credencial ausente. Envie o header Authorization com Bearer.
audience_disabled403Tenant desativado. Nenhuma credencial dele é aceita.

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