Chave de checkout
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:
- Gerar um token de cartão
- Consultar um plano pela página
- Criar uma assinatura pela página
- Consultar uma assinatura pela página
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.
| Caso | Efeito 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ódigo | HTTP | Mensagem |
|---|---|---|
| - | 401 | Chave de checkout ausente. |
| - | 401 | Chave de checkout inválida. |
PZ030 | 403 | Gateway suspenso para esta conta. Fale com o suporte PayZu. |
PZ034 | 404 | Recorrência não ativada para esta conta. |
{
"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.