PayZu GatewaySegurança

Chave de checkout


Nesta páginaComo obter a chaveO que vai em cada chamadaValidade e trocaErros de autenticação

Identifique a sua conta na geração de token de cartão e nas rotas de plano e de assinatura do checkout com uma chave pública, que pode ficar no app ou na página do comprador sem expor a chave de API.

Como obter a chave

A chave de checkout nasce com a conta do PayZu Gateway e aparece no painel. A API não tem rota para consultar nem para trocar a chave. As duas coisas são feitas no painel.

A chave é pública e vai no caminho da url de cada plano, a página de adesão da PayZu. Com ela, qualquer pessoa só consegue:

  • gerar um token de cartão;
  • ler um plano ativo;
  • criar uma assinatura;
  • consultar uma assinatura pelo id.

A consulta da assinatura traz o e-mail, o telefone e o documento do cliente mascarados. A chave não dá acesso às rotas da chave de API.

O que vai em cada chamada

O valor puro da chave vai no cabeçalho x-checkout-key, sem Bearer, nestas rotas:

bash
curl "https://api.sandbox.payzu.dev/v1/checkout/plans/plan_oOsn4Cs4eayZ3LoytwzErn" \
  -H "x-checkout-key: SUA_CHAVE_DE_CHECKOUT"

As rotas de fatura e de link do checkout, em /v1/checkout/invoices/… e /v1/checkout/payment-links/…, não usam chave, porque o id no caminho identifica a cobrança. Veja Checkout.

As rotas de plano e de assinatura do checkout dependem da Recorrência.

Enquanto ela não está ativa na conta, essas rotas respondem 404. A geração de token de cartão não depende dela.

Para testar a chave, abra Gerar um token de cartão na Referência API, cole a chave em Credenciais e clique em Try It!.

Validade e troca

A chave não tem data de vencimento. Ela deixa de valer em dois casos, e nos dois as rotas com a chave respondem 401 com Chave de checkout inválida.

CasoEfeito além do 401
A chave foi trocada no painel.A url de cada plano passa a levar a chave nova, e a url montada com a chave anterior para de funcionar.
A PayZu suspendeu o PayZu Gateway da conta.As rotas de fatura e de link do checkout respondem 403.

Erros de autenticação

CódigoHTTPMensagem
-401Chave de checkout ausente.
-401Chave de checkout inválida.
PZ030403Gateway suspenso para esta conta. Fale com o suporte PayZu.
PZ034404Recorrência não ativada para esta conta.
Resposta 401
{
  "status_code": 401,
  "error": "unauthorized",
  "message": "Chave de checkout inválida.",
  "request_id": "a1b2c3d4-0000-4000-8000-000000000000"
}

O 401 da chave de checkout não traz code. A geração de token e as rotas do checkout também têm limite de chamadas por IP, descrito em Limites de requisição.

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