Autenticação
Nesta página
Como obter a chaveO que vai em cada chamadaValidade e revogaçãoErros de autenticaçãoIdentifique a chamadaAutentique cada chamada com a chave de API da sua conta, sem rota de login nem troca de chave por token.
Como obter a chave
Você cria a chave no painel do PayZu Gateway.
A chave aparece uma única vez, logo depois de criada.
A PayZu não guarda a chave em texto. Copie e guarde no seu servidor, fora do código e do navegador. Se ela vazar, revogue no painel e crie outra.
Em produção, as chamadas vão para https://api.gateway.payzu.com.br. No sandbox, as mesmas rotas atendem em https://api.sandbox.payzu.dev. Veja Ambientes de teste e produção.
O que vai em cada chamada
| Cabeçalho | Valor |
|---|---|
Authorization | Bearer SUA_CHAVE_DE_API |
Content-Type | application/json nas rotas com corpo JSON. A defesa de contestação é a exceção e vai em multipart/form-data. |
curl "https://api.sandbox.payzu.dev/v1/invoices?limit=1" \
-H "Authorization: Bearer SUA_CHAVE_DE_API"Ficam de fora Gerar um token de cartão e as rotas do Checkout, em /v1/checkout/…. O token de cartão e as rotas de plano e de assinatura do checkout usam a chave de checkout. As rotas de fatura e de link do checkout não usam chave.
A chave só alcança os dados da conta dona dela. O id de um recurso de outra conta responde 404, como se não existisse.
Para testar a chave, abra Listar as faturas na Referência API, cole a chave em Credenciais e clique em Try It!. O PayZu Gateway não tem uma rota só de autenticação, e a lista de faturas serve de teste. Com a chave aceita, a resposta é 200 com as faturas da conta, ou items vazio se a conta ainda não tem faturas.
Validade e revogação
A chave não tem data de expiração. Ela para de funcionar quando é revogada no painel, e a chamada seguinte já é recusada.
| Situação | Código |
|---|---|
Chamada sem o cabeçalho Authorization, ou com outro esquema que não Bearer | PZ020 |
| Chave revogada, fora do formato ou que não existe | PZ021 |
| PayZu Gateway da conta suspenso pela PayZu | PZ030 |
Erros de autenticação
| Código | HTTP | Mensagem |
|---|---|---|
PZ020 | 401 | Chave de API ausente. |
PZ021 | 401 | Chave de API inválida. |
PZ030 | 403 | Gateway suspenso para esta conta. Fale com o suporte PayZu. |
{
"status_code": 401,
"error": "unauthorized",
"message": "Chave de API inválida.",
"code": "PZ021",
"request_id": "a1b2c3d4-0000-4000-8000-000000000000"
}Todos os códigos de erro HTTP do PayZu Gateway estão no Catálogo de erros. O motivo da recusa do cartão vem em failure.code da tentativa, como em Vender no cartão.
Identifique a chamada
Toda resposta da API traz o cabeçalho X-Request-Id, que identifica a chamada de forma única. Todo erro traz o mesmo valor em request_id, no corpo. Informe esse valor ao falar com o suporte.
Duas respostas vêm sem o cabeçalho:
- a resposta repetida pela Idempotência, que vem com
Idempotent-Replayed: true; - o
403em HTML da proteção de borda, descrito em Erros.