# Liquerapay

> Liquerapay é uma plataforma brasileira de pagamentos via API. Permite cobrar clientes via Checkout Transparente (PIX QR Code gerado direto na sua aplicação, sem redirecionar o usuário), gerenciar clientes, solicitar saques (payouts) do saldo para uma chave PIX e receber eventos em tempo real via webhooks. Toda a API usa REST + JSON, autenticação Bearer Token e opera em BRL. Base URL: `https://api.liquerapay.com`.

Notas importantes:

- Autenticação: todas as requisições precisam do header `Authorization: Bearer <sua-api-key>`. A chave tem o prefixo `liq_`; o mesmo header também aceita o JWT do painel.
- Não há prefixo de versão na URL (não é `/v1/...`) e não há ambiente de sandbox — só existe produção.
- Valores monetários são sempre em **centavos** (ex.: `5000` = R$ 50,00).
- Respostas seguem o envelope `{ "data": {...}, "error": null, "success": true }` (erro: `{ "error": "CODE", "message": "...", "success": false }`).
- Listas são paginadas por cursor bidirecional: query `limit` (1-100), `after`, `before`; resposta traz `pagination: { hasMore, next, before }`.
- Clientes são únicos por `taxId` (CPF/CNPJ) por merchant — campo obrigatório na criação é `email`, não `taxId`.
- Checkout Transparente gera o PIX imediatamente sem redirecionar o usuário; retorna `brCode` (copia-e-cola) e `imageBase64` (imagem PNG). Só o método `PIX` está disponível hoje. Devolução (`refund`) é sempre integral, sem body — não existe devolução parcial.
- Saques (`withdrawals`) só permitem **um em andamento por vez** — uma nova solicitação enquanto houver `PENDING`/`PROCESSING` retorna `400`.
- Webhooks precisam de URL HTTPS pública e de uma lista `events` (1 a 8) escolhida na criação — o endpoint só recebe os eventos escolhidos. Payloads são assinados no header `Liquera-Signature`, formato `t=<timestamp>,v1=<hmac_sha256_hex>` (HMAC sobre `"${timestamp}.${corpo_bruto}"`, chave = o `secret` devolvido na criação do endpoint). Retry: até 3 tentativas com backoff exponencial; erros `4xx` não são retentados.

## Clientes

- [Referência de Clientes](https://docs.liquerapay.com/pages/customers/reference): Clientes pré-cadastrados para reutilizar em cobranças. Único por `taxId` (CPF/CNPJ) por merchant; campo obrigatório: `email`. Não existe rota para editar um cliente já criado.
- [POST /customers](https://docs.liquerapay.com/pages/customers/create): Cria um cliente. Obrigatório: `email`. Opcionais: `name`, `taxId`, `phone`.
- [GET /customers](https://docs.liquerapay.com/pages/customers/list): Lista os clientes (filtros: `id`, `email`, `taxId`).
- [GET /customers/{id}](https://docs.liquerapay.com/pages/customers/get): Busca um cliente pelo ID.
- [DELETE /customers/{id}](https://docs.liquerapay.com/pages/customers/delete): Remove (soft-delete) um cliente pelo ID.

## Checkout Transparente (PIX embutido)

- [Referência do Checkout Transparente](https://docs.liquerapay.com/pages/transparents/reference): Gera um QR Code PIX direto na sua aplicação, sem redirecionar o usuário. Retorna `brCode` (copia-e-cola) e `imageBase64` (imagem PNG base64). Apenas PIX suportado atualmente.
- [POST /transparents/create](https://docs.liquerapay.com/pages/transparents/create): Cria uma cobrança PIX. Obrigatórios: `method` (`"PIX"`), `amount` (centavos). Opcionais: `description`, `customerId`, `expiresIn` (segundos, padrão 86400).
- [GET /transparents/list](https://docs.liquerapay.com/pages/transparents/list): Lista as cobranças (filtros: `id`, `email`, `status`).
- [GET /transparents/check](https://docs.liquerapay.com/pages/transparents/get): Consulta uma cobrança pelo `id` (query string, não path). Traz `end2endId` e customer completo.
- [POST /transparents/refund](https://docs.liquerapay.com/pages/transparents/refund-create): Devolve uma cobrança paga. `id` via query string, sem body — devolução sempre integral.

## Saques (Withdrawals)

- [Referência de Saques](https://docs.liquerapay.com/pages/withdrawals/reference): Saque do saldo `available` do merchant para uma chave PIX. Mínimo 50 centavos (R$ 0,50), máximo 100.000.000 (R$ 1.000.000,00). Só um saque em andamento por vez.
- [POST /withdrawals](https://docs.liquerapay.com/pages/withdrawals/create): Solicita um saque. Obrigatórios: `amount`, `pixKey`, `pixKeyType` (`CPF`, `CNPJ`, `EMAIL`, `TELEFONE`, `CHAVE_ALEATORIA`). Opcionais: `description`, `taxId`. Status inicial: `PENDING`.
- [GET /withdrawals](https://docs.liquerapay.com/pages/withdrawals/list): Lista os saques (filtro: `status`).
- [GET /withdrawals/{id}](https://docs.liquerapay.com/pages/withdrawals/get): Busca um saque pelo ID. `failedReason` disponível quando `status = FAILED`.

## Webhooks

- [Referência de Webhooks](https://docs.liquerapay.com/pages/webhooks/reference): Notificações automáticas de eventos. Eventos disponíveis: `CHARGE_PAID`, `CHARGE_EXPIRED` (reservado, ainda não disparado), `REFUND_COMPLETED`, `REFUND_FAILED`, `WITHDRAWAL_COMPLETED`, `WITHDRAWAL_FAILED`, `CHECKOUT_PAID`, `CHECKOUT_REFUNDED`. Endpoint deve ser HTTPS público. Payloads assinados via HMAC no header `Liquera-Signature`.
- [POST /webhooks](https://docs.liquerapay.com/pages/webhooks/create): Cria um endpoint. Obrigatórios: `url` (HTTPS), `events` (array, 1 a 8). Retorna `secret` (chave de assinatura) uma única vez.
- [GET /webhooks](https://docs.liquerapay.com/pages/webhooks/list): Lista os endpoints cadastrados (sem `secret`).
- [GET /webhooks/{id}](https://docs.liquerapay.com/pages/webhooks/get): Busca um endpoint pelo ID.
- [GET /webhooks/{id}/deliveries](https://docs.liquerapay.com/pages/webhooks/deliveries): Histórico de entregas (status HTTP, sucesso, tentativa, erro) — útil para debugar falhas.
- [DELETE /webhooks/{id}](https://docs.liquerapay.com/pages/webhooks/delete): Remove um endpoint. Não existe rota para editar/pausar um endpoint sem removê-lo.