PayZu GatewaySegurança

Autenticação


Nesta páginaComo obter a chaveO que vai em cada chamadaValidade e revogaçãoErros de autenticaçãoIdentifique a chamada

Autentique 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çalhoValor
AuthorizationBearer SUA_CHAVE_DE_API
Content-Typeapplication/json nas rotas com corpo JSON. A defesa de contestação é a exceção e vai em multipart/form-data.
bash
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çãoCódigo
Chamada sem o cabeçalho Authorization, ou com outro esquema que não BearerPZ020
Chave revogada, fora do formato ou que não existePZ021
PayZu Gateway da conta suspenso pela PayZuPZ030

Erros de autenticação

CódigoHTTPMensagem
PZ020401Chave de API ausente.
PZ021401Chave de API inválida.
PZ030403Gateway suspenso para esta conta. Fale com o suporte PayZu.
Resposta 401
{
  "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 403 em HTML da proteção de borda, descrito em Erros.