# ZynPay

> ZynPay é um gateway de pagamentos Pix para negócios que precisam receber, conciliar e sacar com previsibilidade. Base URL da API: `https://api.zynpay.com.br`. Todo valor monetário é um inteiro em centavos (R$ 10,00 = `1000`).

- Autenticação por chave de API (`Authorization: Bearer zpk_live_...`) para criar cobranças e consultar saldo. Escopos: `pix:read`, `pix:write`, `balance:read`.
- Saques, chaves de API e webhooks só podem ser gerenciados com login de sessão (e-mail + código, sem senha) — nunca com uma chave de API, por segurança.
- Toda requisição de criação de cobrança exige o cabeçalho `Idempotency-Key`.
- Webhooks são assinados com HMAC-SHA256 no cabeçalho `x-zinpay-signature`, calculado sobre o corpo bruto da requisição.
- Erros seguem sempre o formato `{"error": {"code", "message", "fields", "requestId"}}`.

## Primeiros passos

- [Introdução](https://docs.zynpay.com.br/): O que é a ZynPay e como o produto funciona (painel ou API).
- [Criar conta](https://docs.zynpay.com.br/primeiros-passos/criar-conta): Cadastro sem senha — login por código de e-mail (6 dígitos, válido 10 min) ou Google/Discord.
- [Verificação de conta](https://docs.zynpay.com.br/primeiros-passos/verificacao-de-conta): Status `pending`, `verified`, `suspended`, `closed`. Cobranças e saques exigem `verified`.
- [Segurança da conta](https://docs.zynpay.com.br/primeiros-passos/seguranca-da-conta): Autenticação em duas etapas (TOTP, 6 dígitos, 30s) com 8 códigos de recuperação de uso único.

## Cobranças Pix

- [Gerar cobrança pelo painel](https://docs.zynpay.com.br/cobrancas/gerar-cobranca): Passo a passo no dashboard — valor mínimo R$ 0,80, expiração configurável.
- [Ciclo de vida de uma cobrança](https://docs.zynpay.com.br/cobrancas/ciclo-de-vida): Status `created` → `pending` → `paid` | `expired` | `cancelled` | `failed` | `refunded`. `paid` é definitivo.
- [Link de pagamento (checkout)](https://docs.zynpay.com.br/cobrancas/link-de-pagamento): Toda cobrança gera um link público de checkout com QR Code, sem necessidade de login.
- [Taxas de cobrança](https://docs.zynpay.com.br/cobrancas/taxas): Modelos `fixed`, `percentage` ou `combined`. `netAmountCents = amountCents - feeCents`.

## Saques

- [Como sacar](https://docs.zynpay.com.br/saques/como-sacar): Exige chave Pix cadastrada. Status `requested` → `under_review` → `approved` → `paid`, ou `rejected` (libera o saldo reservado). O valor fica reservado no momento da solicitação, antes da análise.
- [Limites e taxas de saque](https://docs.zynpay.com.br/saques/limites-e-taxas): Taxa padrão R$ 5,00. Padrões: máximo R$ 1.000,00 por saque, limite diário R$ 5.000,00, limite noturno (22h–6h, horário de Brasília) R$ 1.000,00.

## API

- [Visão geral da API](https://docs.zynpay.com.br/api/visao-geral): Base URL, formato de valores, o que uma chave de API pode e não pode fazer.
- [Autenticação](https://docs.zynpay.com.br/api/autenticacao): Como criar uma chave de API (`zpk_live_...`), escopos disponíveis, expiração e revogação.
- [POST /v1/public/pix/charges](https://docs.zynpay.com.br/api/criar-cobranca): Criar cobrança. Obrigatório: `amountCents` (mínimo `80`). Opcionais: `description` (até 255), `externalReference` (até 255), `expiresInSeconds` (`60`–`604800`), `customer.{name,email,externalId}`. Cabeçalho obrigatório: `Idempotency-Key`. Retorna `charge.{id,status,amountCents,feeCents,netAmountCents,pixBrCode,pixQrCodeImage,expiresAt}`.
- [GET /v1/public/pix/charges](https://docs.zynpay.com.br/api/listar-cobrancas): Lista as 100 cobranças mais recentes. Exige escopo `pix:read`.
- [GET /v1/public/pix/charges/{id}](https://docs.zynpay.com.br/api/consultar-cobranca): Consulta uma cobrança específica. Exige escopo `pix:read`.
- [GET /v1/public/pix/balance](https://docs.zynpay.com.br/api/consultar-saldo): Saldo da conta — `availableCents`, `reservedCents`, `blockedCents`. Exige escopo `balance:read`.
- [Webhooks](https://docs.zynpay.com.br/api/webhooks): Eventos `pix.charge.paid`, `withdrawal.paid`, `withdrawal.rejected`, `infraction.updated`. Payload `{id, type, createdAt, data}`. Cabeçalhos `x-zinpay-event-id` e `x-zinpay-signature` (HMAC-SHA256 hex do corpo bruto com o webhook secret `zwhsec_...`). Reentrega com backoff exponencial até `dead_letter`.
- [Erros](https://docs.zynpay.com.br/api/erros): Formato `{"error":{"code","message","fields","requestId"}}`. Códigos comuns: `INVALID_API_KEY` (401), `ACCOUNT_NOT_VERIFIED` (403), `IDEMPOTENCY_KEY_REUSED` (409), `PAYOUTS_PAUSED` (409), `FEE_EXCEEDS_AMOUNT` (422), `PIX_KEY_REQUIRED` (422).