Integração

Chaves de API

Aprenda como funcionam as chaves de API e como utilizá-las para acessar a HyzePay.

A chave de API é sua credencial de acesso à HyzePay. Ela identifica sua conta e autoriza cada requisição enviada para a nossa API. Sem uma chave válida, nenhum pedido será aceito.

O que você pode fazer com suas chaves

As chaves de API são gerenciadas diretamente pelo dashboard. Com elas, você pode:

Ver todas as chaves ativas
Criar novas chaves para diferentes projetos
Revogar chaves comprometidas ou que não são mais usadas

Endpoint e autenticação

Todas as requisições da API pública usam o prefixo /api/v1. Envie a chave em um destes headers:

Authorization: Bearer hzp_live_…
X-API-Key: hzp_live_…

Saiba mais sobre autenticação e pagamentos na visão geral da API.

Erro de Autenticação (401)

Você receberá um HTTP 401 quando:

A chave não for enviada no header
A chave for inválida, revogada ou inexistente
O formato do header estiver incorreto

Permissões da chave de API

Cada chave possui escopos (scopes) que limitam o que ela pode fazer na API. Isso reduz o impacto se uma chave vazar.

Permissões disponíveis

Scope	Permite
`payments:read`	Consultar e listar pagamentos
`payments:write`	Criar e cancelar pagamentos
`*`	Acesso total

Chaves criadas pelo dashboard já vêm com payments:read + payments:write.

Boas práticas de segurança

Nunca use a API Key no frontend (browser, app mobile exposto). Só no seu servidor.
Guarde a secret em variáveis de ambiente (HYZEPAY_API_KEY), nunca em repositório git.
A secret só aparece uma vez na criação — copie e armazene com segurança.
Revogue chaves antigas ou suspeitas no dashboard assim que possível.
Use chaves diferentes por ambiente/projeto (staging vs produção).
A criação de chaves exige 2FA ativo na conta.

Como criar uma chave de API

No dashboard: Integração → API → Nova chave.

Se o 2FA não estiver ativo, o fluxo pede ativação (QR + app autenticador).
Com 2FA ativo, informe a descrição e o código de 6 dígitos para gerar.

Via API (sessão logada no dashboard + 2FA):

POST /api/api-keys
Content-Type: application/json

{
  "name": "Meu backend",
  "totpCode": "123456"
}

Exemplo de uso da chave em uma cobrança PIX:

curl -X POST "$HYZEPAY_BASE_URL/api/v1/payments" \
  -H "Authorization: Bearer $HYZEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount_cents": 1500, "description": "Pedido #1001" }'

Prefixo das chaves: hzp_live_…. Após criar, salve no .env do seu backend:

HYZEPAY_API_KEY=hzp_live_XXXXXXXXXXXXXXXXXXXXXXXX
HYZEPAY_BASE_URL=https://hyzepay.pro