> ## Documentation Index
> Fetch the complete documentation index at: https://docs.liquerapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Glossário

> Termos usados na API Liquerapay.

## Recursos

<AccordionGroup>
  <Accordion title="Merchant" icon="store">
    A sua **conta/loja** dentro da Liquerapay. Toda chave de API e todo
    recurso (cobranças, clientes, saques) pertence a um merchant.
  </Accordion>

  <Accordion title="Customer" icon="user">
    Um **cliente final** que paga você. Cadastrar customers é opcional, mas
    facilita identificação e relatórios. Identificado por CPF/CNPJ único por
    merchant.
  </Accordion>

  <Accordion title="Charge" icon="qrcode">
    Uma **cobrança PIX**: gera um QR Code (texto copia-e-cola + imagem base64)
    para o cliente pagar. Tem ciclo de vida: `PENDING → PAID/EXPIRED`, e uma
    cobrança `PAID` pode virar `REFUNDED` ou `DISPUTED`.
  </Accordion>

  <Accordion title="Refund" icon="rotate-left">
    Uma **devolução integral** de uma cobrança paga (não há devolução
    parcial). Debita do saldo do merchant — a taxa cobrada na cobrança
    original **não é devolvida**.
  </Accordion>

  <Accordion title="Withdrawal" icon="money-bill-transfer">
    Um **saque** do saldo do merchant para uma chave PIX. Paga uma taxa
    adicional debitada do saldo.
  </Accordion>

  <Accordion title="Webhook Endpoint" icon="webhook">
    Uma **URL HTTPS** cadastrada para receber eventos. Você escolhe quais
    eventos (`events`) ele recebe, e cada endpoint tem um `secret` — a
    chave de assinatura usada para validar a autenticidade das requisições.
  </Accordion>
</AccordionGroup>

## Conceitos

<AccordionGroup>
  <Accordion title="Centavos">
    **Todos os valores monetários são em centavos** (inteiros). Uma cobrança
    de R\$ 50,00 é representada como `5000`. Nunca use float.
  </Accordion>

  <Accordion title="Saldo (available / pending / blocked)">
    * **available**: pronto para saque
    * **pending**: aguardando confirmação (D+0 normalmente)
    * **blocked**: bloqueado por disputas/infrações
  </Accordion>

  <Accordion title="Taxa (feeCents)">
    Valor descontado da cobrança ou debitado do saldo no saque. O valor
    exato depende do contrato do merchant.
  </Accordion>

  <Accordion title="EndToEndId (E2E)">
    Identificador único do PIX no sistema do Banco Central. Necessário
    para solicitar devoluções.
  </Accordion>

  <Accordion title="Cursor pagination">
    Paginação bidirecional via `after`/`before` (cursores opacos retornados
    em `pagination`). Mais consistente que offset em listas que mudam com
    frequência.
  </Accordion>

  <Accordion title="HMAC Signature">
    Assinatura no header `Liquera-Signature` (formato `t=<timestamp>,v1=<hmac>`),
    calculada com HMAC-SHA256 sobre `"${timestamp}.${corpo bruto}"` usando o
    `secret` do webhook. Permite verificar que a requisição realmente veio
    da Liquerapay — veja o [guia de webhooks](/pages/start/webhooks).
  </Accordion>
</AccordionGroup>

## Status de cobranças

| Status     | Significado                                   |
| ---------- | --------------------------------------------- |
| `PENDING`  | QR Code emitido, aguardando pagamento         |
| `PAID`     | Pago — saldo creditado                        |
| `EXPIRED`  | Tempo limite atingido sem pagamento           |
| `REFUNDED` | Cobrança paga foi devolvida integralmente     |
| `DISPUTED` | Há uma infração/MED aberta contra o pagamento |

## Status de saques

| Status       | Significado                          |
| ------------ | ------------------------------------ |
| `PENDING`    | Solicitado, aguardando processamento |
| `PROCESSING` | Sendo enviado pelo PSP               |
| `COMPLETED`  | PIX enviado com sucesso              |
| `FAILED`     | Falhou — ver `failedReason`          |

## Tipos de chave PIX

| Tipo              | Formato                     |
| ----------------- | --------------------------- |
| `CPF`             | 11 dígitos (apenas números) |
| `CNPJ`            | 14 dígitos (apenas números) |
| `EMAIL`           | E-mail válido               |
| `TELEFONE`        | `+5511999999999`            |
| `CHAVE_ALEATORIA` | Chave aleatória (UUID/EVP)  |