# HyzePay

> Gateway de pagamento brasileiro focado em PIX. API REST simples, webhooks com HMAC e pronta para integração por humanos ou IAs.

HyzePay é um gateway de pagamento que simplifica cobranças PIX. A API externa (v1) gera QR codes, consulta status e notifica via webhooks. Valores em centavos (`amount_cents`). Auth por API Key (`hzp_live_…`). Nunca use a API Key no browser — só no backend.

Base URL de produção: `https://hyzepay.pro` (ou o domínio da sua instância).
Prefixo da API pública: `/api/v1`
Formato: JSON (`Content-Type: application/json`)

## Documentação principal

- [Documentação completa (site)](https://hyzepay.pro/docs): hub da API, guias e referência
- [Contexto completo para IA (llms-full.txt)](https://hyzepay.pro/llms-full.txt): API + webhooks + exemplos em um único arquivo
- [Chaves de API](https://hyzepay.pro/docs/guias/chaves-de-api): criar, escopos e boas práticas
- [Webhooks](https://hyzepay.pro/docs/webhooks): eventos, HMAC e liberação de produto
- [Segurança de webhooks](https://hyzepay.pro/docs/webhooks/seguranca): validação de assinatura
- [Referência PIX](https://hyzepay.pro/docs/referencia/pix): criar / listar / consultar / cancelar pagamentos
- [CLI](https://hyzepay.pro/docs/cli): ferramenta de linha de comando
- [Changelog](https://hyzepay.pro/docs/changelog): mudanças da API

## Começar em 2 minutos

1. No dashboard: Integração → API → Nova chave (exige 2FA). Copie a secret `hzp_live_…` (só aparece uma vez).
2. Guarde no backend:

```env
HYZEPAY_API_KEY=hzp_live_XXXXXXXXXXXXXXXXXXXXXXXX
HYZEPAY_BASE_URL=https://hyzepay.pro
HYZEPAY_WEBHOOK_SECRET=whsec_…
```

3. Crie um pagamento:

```http
POST /api/v1/payments
Authorization: Bearer hzp_live_…
Content-Type: application/json

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

4. Mostre `payment.pix.br_code` (PIX copia-e-cola) e/ou `payment.pix.qr_code_image`.
5. Confirme o pagamento com webhook `payment.paid` (recomendado) ou polling em `GET /api/v1/payments/:id`.

## Autenticação

Envie a API Key em **um** destes headers:

| Header | Exemplo |
|--------|---------|
| `Authorization` | `Bearer hzp_live_…` |
| `X-API-Key` | `hzp_live_…` |

Escopos: `payments:read`, `payments:write`, `*` (chaves do dashboard já vêm com read+write).

## Endpoints (API v1)

| Método | Path | Auth | Descrição |
|--------|------|------|-----------|
| GET | `/api/v1/health` | pública | Health check |
| POST | `/api/v1/payments` | API Key write | Criar cobrança PIX |
| GET | `/api/v1/payments` | API Key read | Listar (query: status, limit, offset, external_id) |
| GET | `/api/v1/payments/{id}` | API Key read | Consultar por UUID ou `external_id` |
| DELETE | `/api/v1/payments/{id}` | API Key write | Cancelar pendente → `expired` |

### Body de criação (POST /api/v1/payments)

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| `amount_cents` | number | sim* | Valor em centavos (R$ 15,00 → `1500`) |
| `amount` | number | sim* | Alternativa em reais (`15` ou `15.00`) |
| `description` | string | não | Texto do PIX (máx. ~140) |
| `external_id` | string | não | ID no seu sistema — **idempotência** (use sempre) |
| `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 |

\* Informe `amount_cents` **ou** `amount`. Também aceita camelCase (`amountCents`, `externalId`, `expiresIn`).

### Resposta de criação

```json
{
  "payment": {
    "id": "uuid",
    "status": "pending",
    "amount_cents": 1500,
    "amount_label": "R$ 15,00",
    "currency": "BRL",
    "external_id": "pedido-1001",
    "pix": {
      "br_code": "00020126…",
      "qr_code_image": "https://… ou data:image/png;base64,…",
      "expires_at": "2026-07-13T13:00:00.000Z"
    },
    "checkout_url": "https://hyzepay.pro/pay/api_…",
    "created_at": "…",
    "paid_at": null
  },
  "created": true
}
```

- `created: true` → novo pagamento
- `created: false` → já existia com o mesmo `external_id` (não gera segundo PIX)

### Status

| Status | Significado |
|--------|-------------|
| `pending` | Aguardando PIX |
| `paid` | Pago — **só então liberar produto** |
| `expired` | Expirou ou cancelado |
| `failed` | Falha |
| `refunded` | Reembolsado |

### Erros

```json
{ "error": { "code": "invalid_amount", "message": "…", "details": null } }
```

Códigos comuns: `unauthorized`, `invalid_api_key`, `forbidden_scope`, `not_found`, `invalid_amount`, `already_paid`, `pix_generation_failed`.

Header de versão: `X-HyzePay-API-Version: v1`.

## Regras obrigatórias para integração

1. Nunca chamar a API do browser; só do servidor.
2. Sempre enviar `external_id` = id do pedido no seu sistema.
3. Após criar, exibir `payment.pix.br_code` ao usuário.
4. Liberar produto **somente** quando `status === "paid"`.
5. Tratar `created: false` como sucesso (idempotência).
6. Valores sempre em `amount_cents` (inteiro).
7. Preferir webhook `payment.paid` + validação HMAC; polling como fallback (3–5s).

## Webhooks (resumo)

Cadastro: Dashboard → Integração → Webhook (URL HTTPS + secret `whsec_…` + eventos).

Headers importantes:
- `X-HyzePay-Event`: tipo (ex. `payment.paid`)
- `X-HyzePay-Signature`: `t=<unix>,v1=<hmac_hex>`
- `X-HyzePay-Event-Id`: id único do evento

Assinatura HMAC-SHA256:
1. Payload assinado = `${t}.${rawBody}` (body cru, sem re-serializar JSON)
2. `HMAC_SHA256(secret, payload)` em hex
3. Rejeitar se `|now - t| > 300` segundos
4. Comparar com `timingSafeEqual` / `hash_equals`

Eventos: `payment.created`, **`payment.paid`**, `payment.expired`, `payment.failed`, `payment.refunded`, `dispute.created`, `dispute.updated`, `withdrawal.requested`, `withdrawal.paid`, `test`.

Payload v2 (recomendado):

```json
{
  "id": "evt_…",
  "type": "payment.paid",
  "api_version": "v2",
  "data": {
    "object": {
      "id": "uuid",
      "status": "paid",
      "amount_cents": 1990,
      "external_id": "order_123",
      "customer": { "name": "…", "email": "…" },
      "paid_at": "…"
    }
  },
  "source": "hyzepay"
}
```

v1 (legado): `event` + objeto direto em `data` (sem `data.object`).

Responder HTTP 2xx. Retries em falha. Idempotência: ignore `event.id` já processado.

## Prompt pronto para IA

```
Integre a HyzePay External API v1 no meu backend.

Base URL: {{HYZEPAY_BASE_URL}}
Auth: Authorization: Bearer {{HYZEPAY_API_KEY}} (hzp_live_…)
Docs: https://hyzepay.pro/llms-full.txt

Endpoints:
- POST /api/v1/payments → { amount_cents, description?, external_id?, customer?, metadata?, expires_in? }
  → payment.pix.br_code, payment.id, status pending|paid|expired|failed|refunded
- GET /api/v1/payments/:id (UUID ou external_id)
- GET /api/v1/payments?status=&limit=&offset=
- DELETE /api/v1/payments/:id
- GET /api/v1/health

Webhooks: validar X-HyzePay-Signature (HMAC SHA256 de `${t}.${rawBody}`), processar payment.paid, liberar só se status=paid, usar external_id.

Regras: server-side only; sempre external_id; amount_cents; liberar só paid; created:false = ok.
Implemente client tipado + createAndWaitForPayment + handler de webhook com HMAC.
```

## Mapa rápido

| Quero… | Faço… |
|--------|--------|
| Gerar PIX | `POST /api/v1/payments` |
| Ver se pagou | `GET /api/v1/payments/{id}` ou webhook `payment.paid` |
| Listar | `GET /api/v1/payments` |
| Cancelar | `DELETE /api/v1/payments/{id}` |
| API ok? | `GET /api/v1/health` |
| Contexto full para IA | https://hyzepay.pro/llms-full.txt |

## Optional

- [Referência completa da API](https://hyzepay.pro/docs/referencia)
- [Eventos de pagamento](https://hyzepay.pro/docs/webhooks/eventos/pagamentos)
- [FAQ](https://hyzepay.pro/docs/guias/faq)
- [Glossário](https://hyzepay.pro/docs/guias/glossario)
- [Ferramentas (OpenAPI, tipos, HMAC)](https://hyzepay.pro/docs/ferramentas)
- [Dashboard](https://hyzepay.pro/dashboard)