Ajuda

Glossário

Termos técnicos da API e da plataforma HyzePay explicados de forma simples. Use como referência rápida durante a integração.

Autenticação e segurança Pagamentos e cobranças Webhooks e eventos Plataforma e API

Autenticação e segurança

API Key: Credencial secreta que autentica suas requisições na API pública. Na HyzePay começa com hzp_live_…. Envie no header Authorization: Bearer … ou X-API-Key. Nunca use no frontend. Veja o guia Chaves de API.
Scope (escopo): Permissão associada a uma chave. Exemplos: payments:read (consultar), payments:write (criar/cancelar), * (tudo). Sem o escopo certo a API responde 403 forbidden_scope.
2FA (autenticação em dois fatores): Código de 6 dígitos gerado por app autenticador, exigido para criar chaves de API no dashboard e reforçar a segurança da conta.
HMAC / Assinatura: Assinatura criptográfica enviada nos webhooks no header X-HyzePay-Signature (t=…,v1=…). Valida que o evento veio da HyzePay e não foi adulterado. Use o raw body + secret whsec_….
Secret (webhook): Segredo gerado no cadastro do webhook (whsec_…). Serve só para validar a assinatura HMAC no seu servidor. Não compartilhe e não exponha no cliente.

Pagamentos e cobranças

Payment: Objeto principal da API v1. Representa uma cobrança PIX com id, status, valor, dados do cliente, PIX e metadados. Criado via POST /api/v1/payments.
amount_cents: Valor da cobrança em centavos. Ex.: R$ 15,00 → 1500. Alternativa: campo amount em reais (15 ou 15.00).
external_id: ID do pagamento no seu sistema (ex.: pedido-1001). Torna a criação idempotente: repetir o POST devolve o mesmo payment, sem gerar outro PIX.
Idempotência: Garantia de que reenviar a mesma operação não cria efeitos duplicados. Na HyzePay, use external_id estável nos pagamentos e ignore event ids já processados nos webhooks.
Status do pagamento: Ciclo de vida da cobrança: pending (aguardando), paid (confirmado — liberar produto), expired, failed, refunded.
PIX / br_code: Meio de pagamento instantâneo. pix.br_code é o copia-e-cola; pix.qr_code_image é a imagem do QR. pix.expires_at indica até quando vale a cobrança.
checkout_url: URL da página de checkout hospedada na HyzePay (/pay/…). Opcional: redirecione o cliente para pagar sem montar a UI do PIX no seu front.
expires_in: Tempo de validade do PIX em segundos (entre 60 e 86400). Default: 24 horas.
correlation_id: Identificador da cobrança no provedor PIX (Woovi). Útil para suporte e conciliação interna.
metadata: Objeto JSON livre que você envia na criação e recebe de volta nas consultas. Serve para amarrar o payment ao seu domínio (user_id, plan, etc.).
Polling: Consultar repetidamente GET /api/v1/payments/:id até o status mudar (ex.: a cada 3–5s). Alternativa (ou complemento) aos webhooks.

Webhooks e eventos

Webhook: Endpoint HTTPS no seu servidor que a HyzePay chama com um POST quando algo acontece (ex.: pagamento confirmado). Cadastre em Integração → Webhook.
Evento (payment.paid): Tipo de notificação enviado no header X-HyzePay-Event. O mais importante para liberar produto é payment.paid. Outros exemplos: disputa, saque, expiração.
Retry (reenvio): Nova tentativa de entrega do webhook se o seu endpoint falhar (timeout, 5xx, rede). Por isso o handler deve ser idempotente.
Raw body: Corpo HTTP original (string de bytes) da requisição de webhook. Obrigatório para validar HMAC — não use JSON.stringify(JSON.parse(body)), que quebra a assinatura.

Plataforma e API

API v1: Versão atual da API pública, prefixo /api/v1. Respostas incluem o header X-HyzePay-API-Version: v1.
Base URL: Domínio da sua instância HyzePay (ex.: https://hyzepay.pro). Combine com o path: /api/v1/payments.
Dashboard: Painel web da HyzePay onde você gerencia chaves, webhooks, cobranças, saques e configurações da conta. Ações sensíveis usam sessão + 2FA, não a API key pública.
Gateway / Woovi: Infraestrutura de PIX por baixo da HyzePay. Você integra só com a API HyzePay; a geração e liquidação do PIX passam pelo gateway configurado.
Envelope de erro: Formato padrão de falha: { error: { code, message, details } }. Exemplos de code: invalid_amount, unauthorized, not_found.
Customer: Dados opcionais do pagador na criação do payment: nome, e-mail, documento (CPF/CNPJ) e telefone.
Saque (withdrawal): Transferência do saldo da conta HyzePay para a conta bancária cadastrada. Pode gerar eventos de webhook (withdrawal.*) conforme o status.
Disputa: Contestação de um pagamento. Pode gerar hold no valor e eventos no webhook. Acompanhe no dashboard e pela API de disputas quando disponível.

Was this page helpful?