Skip to main content
Toda requisição à API da Z2Pay é autenticada por uma API key, enviada no header x-api-key.
A secret key (sk) dá acesso total à sua conta. Nunca a exponha no frontend, em apps mobile, em repositórios públicos ou em logs. Use-a apenas no seu servidor.

​
Formato da chave

As chaves seguem o padrão z2_{ambiente}_{tipo}_{aleatório} (256 bits de entropia):

​
Secret (sk) × Publishable (pk)

Secret key (sk)

Acesso completo (criar, ler, atualizar, estornar). Somente no backend.

Publishable key (pk)

Acesso restrito a operações públicas (ex.: tokenização no frontend). Pode ser exposta no navegador.

​
Como obter sua chave

  1. Acesse o Dashboard da Z2Pay.
  2. Para chaves de teste, entre no ambiente de sandbox e gere as credenciais lá.
  3. Para chaves de produção, gere no ambiente de produção.
  4. Copie a chave no momento da criação — por segurança, ela é exibida apenas uma vez (depois fica mascarada, ex.: z2_live_sk_KxY8…3pQ1).
Uma única chave da conta vale para todos os produtos — Core, Assinaturas e Checkout ficam sob a mesma URL base (https://api.z2pay.com/v1) e se distinguem apenas pelo caminho. As chaves antigas por produto (z2_psp_... / z2_chk_...) continuam válidas.
Chaves de sandbox e de produção têm o mesmo formato, mas são geradas em ambientes diferentes e não são intercambiáveis. Uma chave de sandbox só funciona em *.sandbox.z2pay.com.

​
Respostas de autenticação

Nos dois casos, error é texto, não objeto — error.code é undefined. O guard de autenticação responde antes de chegar à aplicação, e o envelope { error: { code, message } } é dos erros de domínio. Ramifique pelo status HTTP. Veja as exceções de formato em Erros.

​
Boas práticas

Use variáveis de ambiente

Carregue a chave de uma variável de ambiente/secret manager, nunca hardcoded no código.

Rotacione se vazar

Suspeitou de vazamento? Gere uma nova chave e revogue a antiga no Dashboard.

Uma chave por ambiente

Separe claramente as chaves de sandbox e de produção na sua aplicação.

Restrinja no frontend

No navegador/app use apenas a pk. A sk jamais sai do servidor.