Comece aqui

Autenticação


Nesta páginaFormas de autenticarPeça o tokenErros de autenticação

Autentique cada chamada na forma que o seu produto exige.

Formas de autenticar

FormaProdutosOnde vaiValidade
Token Bearer da contaPayZu PixAuthorization: Bearer <token>Sem troca; no sandbox, a credencial vale 24 horas
Credencial trocada por tokenPayZu Conta HubAuthorization: Bearer <access_token>15 minutos (expires_in: 900)
Certificado mTLS com tokenPayZu Payments e recorrência no cartãoCertificado na conexão e Authorization: Bearer <access_token>expires_in, em segundos
Chave de checkoutCheckout e token de cartão do PayZu GatewayHeader x-checkout-keySem troca de token
Chave de APIPayZu GatewayAuthorization: Bearer <chave>, só a partir do seu servidorSem troca de token
Chave de APIPayZu CâmbioAuthorization: Bearer <chave>Sem troca de token; a chave vence na data de expiresAt
Conta de serviço com troca de tokenPayZu OnboardingAuthorization: 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

ProdutoRegra da troca
PayZu Conta HubO corpo vai em JSON ou em application/x-www-form-urlencoded. A lista de IPs da credencial vale nesta rota também.
PayZu PaymentsO certificado vai em toda conexão, a menos que a PayZu desligue a exigência na credencial.
PayZu OnboardingA 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ódigoHTTPMensagem
PZA100401Unauthorized
PZA200403Forbidden
PZA203403Acesso não permitido a partir do endereço de IP 203.0.113.10.
PZA205403Conta com token de saque exige IP cadastrado na whitelist. Cadastre o IP de origem (203.0.113.10) antes de operar.
PZA206403Conta aguardando assinatura do contrato. Assine o contrato enviado ao representante legal para liberar as operações.

Os códigos do PayZu Câmbio estão em Autenticação do produto, e a lista inteira, no Catálogo de erros.