HyperPag
EN

Developers

API de pagamentos e Webhooks

Integre cobranças Pix ao seu sistema com a API HyperPag: links de pagamento, checkout Pix e webhooks de pagamento em tempo real.

Visão geral

A API HyperPag é REST sobre HTTPS, com versionamento por URL (prefixo /v1) e respostas em JSON. Base URL:

Base URL
https://api.hyperpag.com/v1

O healthcheck é público e pode ser usado para monitoramento:

Requisição
curl -X GET https://api.hyperpag.com/v1/health

Autenticação por API Key

Gere suas chaves no painel (Desenvolvedor → API Keys). Chaves de produção usam o prefixo hpg_live_, têm escopos por recurso e são exibidas uma única vez na criação. Envie a chave no header Authorization:

Header (chave fictícia de exemplo)
Authorization: Bearer hpg_live_EXAMPLE_DO_NOT_USE

Endpoints financeiros de escrita exigem também o header Idempotency-Key para evitar duplicação em retries.

Fluxo de pagamento

  1. 01Crie um link de pagamento (no painel ou via API) com valor fixo ou aberto.
  2. 02O pagador abre o checkout, informa os dados e recebe o QR Code Pix + copia e cola.
  3. 03Ao pagar, a confirmação chega por webhook do gateway e o pagamento vira PAID.
  4. 04O valor líquido é creditado no ledger e compõe o saldo disponível do painel.

Webhooks de pagamento

Cadastre endpoints no painel (Desenvolvedor → Webhooks) e receba eventos em tempo real. Cada entrega é assinada com HMAC para verificação de origem, com logs e replay disponíveis no painel.

payment.created

Nova cobrança criada (link, checkout ou API).

payment.paid

Pagamento confirmado — o Pix foi recebido.

payment.failed

Falha ao processar o pagamento.

payment.canceled

Cobrança cancelada.

payment.refunded

Pagamento estornado.

payment.expired

Cobrança expirada sem pagamento.

Ao cadastrar um endpoint, escolha os eventos que deseja receber (ou use * para todos).

Payload de exemplo (ilustrativo)
{
  "event": "payment.paid",
  "paymentId": "pay_example",
  "status": "PAID",
  "amountCents": 50000
}

Status de pagamento

PENDINGPROCESSINGPAIDFAILEDCANCELEDREFUNDEDEXPIRED

As transições seguem uma máquina de estados no servidor — transições inválidas são rejeitadas e cada mudança fica registrada no histórico do pagamento.

Segurança

  • HTTPS obrigatório em todas as chamadas.
  • API Keys com escopos, rotação e revogação imediata.
  • Idempotência em endpoints financeiros (header Idempotency-Key).
  • Webhooks assinados com HMAC; valide a assinatura antes de processar.
  • Rate limiting por origem.

Gere suas chaves e endpoints no painel: app.hyperpag.com