> ## 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.

# Referência

> Crie cobranças PIX (QR Code copia-e-cola) direto pela API e gerencie devoluções.

**Checkout Transparente** é a forma de criar cobranças PIX chamando a API
diretamente e renderizando o QR Code na sua própria interface — sem redirecionar
o cliente para uma página hospedada pela Liquerapay. Use quando você quer
controle total sobre a experiência de pagamento no seu app/site.

<Note>
  Também existe o **Checkout Hospedado** (carrinho com produtos + página de
  pagamento hospedada pela Liquerapay, incluindo links de pagamento
  reutilizáveis). Essa documentação chega em breve — por enquanto, esta seção
  cobre apenas o fluxo transparente (`/transparents/*`).
</Note>

## Fluxo padrão

<Steps>
  <Step title="Criar a cobrança">
    `POST /transparents/create` com `amount` e `method: "PIX"`. Recebe o `brCode`.
  </Step>

  <Step title="Apresentar ao cliente">
    Renderize a `imageBase64` ou ofereça o `brCode` (copia-e-cola).
  </Step>

  <Step title="Cliente paga">
    O PSP confirma o pagamento. A cobrança vira `PAID` e creditamos seu saldo.
  </Step>

  <Step title="Você é notificado">
    Disparamos o webhook `CHARGE_PAID` para os endpoints inscritos nesse evento.
  </Step>
</Steps>

## Ciclo de vida

```mermaid theme={null}
flowchart LR
  PENDING --> PAID
  PENDING --> EXPIRED
  PAID --> REFUNDED
  PAID --> DISPUTED
```

| 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 |

## Campos da cobrança

| Campo         | Obrigatório? | Descrição                                                                                          |
| ------------- | ------------ | -------------------------------------------------------------------------------------------------- |
| `method`      | **Sim**      | Fixo em `"PIX"` — hoje é o único método suportado                                                  |
| `amount`      | **Sim**      | Valor em centavos (mínimo 100, máximo 100.000.000), sujeito ao `minTicket`/`maxTicket` do merchant |
| `description` | Não          | Texto exibido no app de pagamento (até 140 caracteres)                                             |
| `customerId`  | Não          | ID de um customer já cadastrado                                                                    |
| `expiresIn`   | Não          | Validade do QR Code **em segundos** (60 a 2.592.000, padrão 86400 = 24h)                           |

## Exemplo

```bash theme={null}
POST /transparents/create
{
  "method": "PIX",
  "amount": 5000,
  "description": "Pedido #1234",
  "customerId": "cust_018f3a2b7c4d7c40a1b2",
  "expiresIn": 1800
}
```

**Resposta:**

```json theme={null}
{
  "data": {
    "id": "chg_018f8e2d9a5f7b10c3d4",
    "amount": 5000,
    "status": "PENDING",
    "txid": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f",
    "brCode": "00020126580014BR.GOV.BCB.PIX0136abc...6304ABCD",
    "imageBase64": "data:image/png;base64,iVBORw0KGgoAAAA...",
    "expiresAt": "2026-04-19T19:02:11.420Z",
    "customer": {
      "id": "cust_018f3a2b7c4d7c40a1b2",
      "name": "João Silva",
      "taxId": "12345678900",
      "email": "joao@exemplo.com"
    },
    "createdAt": "2026-04-19T18:32:11.420Z"
  },
  "error": null,
  "success": true
}
```

## Devoluções (refunds)

Cobranças `PAID` podem ser **devolvidas integralmente** via
[`POST /transparents/refund`](/pages/transparents/refund-create). Regras:

* A devolução é **sempre do valor total** — não há devolução parcial
* A taxa cobrada na cobrança original **não é devolvida**
* O merchant precisa ter saldo disponível para cobrir o valor da devolução

## Operações disponíveis

| Operação                                                 | Endpoint                    |
| -------------------------------------------------------- | --------------------------- |
| [Criar cobrança](/pages/transparents/create)             | `POST /transparents/create` |
| [Listar cobranças](/pages/transparents/list)             | `GET /transparents/list`    |
| [Consultar cobrança](/pages/transparents/get)            | `GET /transparents/check`   |
| [Solicitar devolução](/pages/transparents/refund-create) | `POST /transparents/refund` |