PIX (API Key)

Pagamentos PIX

API pública para gerar cobranças PIX, consultar status e cancelar. Prefixo /api/v1. Auth por API Key.

Use payment.pix.br_code no copia-e-cola e confirme com webhook payment.paid ou polling em GET /api/v1/payments/:id.

Criar pagamento

Gera um PIX (Woovi) e devolve QR / copia-e-cola. Scope payments:write.

POST/api/v1/payments

Autenticação: API Key (Bearer hzp_live_… ou X-API-Key)

Parâmetros

Campo	Tipo	Obrigatório	Descrição
`amount_cents`	number	sim	Valor em centavos (ou use amount em reais)
`amount`	number	não	Alternativa em reais (15 ou 15.00)
`description`	string	não	Texto do PIX (máx. ~140)
`external_id`	string	não	Seu ID — torna a criação idempotente
`expires_in`	number	não	Segundos até expirar (60–86400). Default 24h
`customer`	object	não	name, email, document, phone
`metadata`	object	não	JSON livre

Exemplo de body

{
  "amount_cents": 1500,
  "description": "Pedido #1001",
  "external_id": "pedido-1001",
  "customer": {
    "name": "Maria Silva",
    "email": "maria@email.com",
    "document": "12345678909"
  }
}

Exemplo de resposta

{
  "payment": {
    "id": "uuid",
    "status": "pending",
    "amount_cents": 1500,
    "amount_label": "R$ 15,00",
    "pix": {
      "br_code": "00020126…",
      "qr_code_image": "https://…",
      "expires_at": "…"
    },
    "checkout_url": "https://…/pay/api_…",
    "external_id": "pedido-1001"
  },
  "created": true
}

Listar pagamentos

Lista pagamentos da conta. Scope payments:read. Query: limit, status.

GET/api/v1/payments

Autenticação: API Key (Bearer hzp_live_… ou X-API-Key)

Exemplo de resposta

{
  "payments": [ /* Payment[] */ ],
  "pagination": { "has_more": false }
}

Buscar pagamento

Consulta por UUID HyzePay ou external_id. Se pending, pode sincronizar com o gateway.

GET/api/v1/payments/{id}

Autenticação: API Key (Bearer hzp_live_… ou X-API-Key)

Exemplo de resposta

{
  "payment": {
    "id": "uuid",
    "status": "paid",
    "amount_cents": 1500,
    "paid_at": "2026-07-13T12:05:00.000Z"
  }
}

Cancelar / expirar

Cancela cobrança pendente (status → expired). Scope payments:write.

DELETE/api/v1/payments/{id}

Autenticação: API Key (Bearer hzp_live_… ou X-API-Key)

Health

Checagem de saúde da API (sem auth).

GET/api/v1/health

Público — sem autenticação

Exemplo de resposta

{
  "ok": true,
  "service": "hyzepay-api",
  "version": "v1",
  "gateway": { "provider": "woovi", "configured": true }
}