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

# Quickstart

> Crie sua primeira cobrança PIX em menos de 5 minutos.

Vamos do zero ao primeiro QR Code PIX. Você precisará apenas de uma chave
de API gerada no [painel](https://app.liquerapay.com).

## 1. Configure o ambiente

Defina sua chave em uma variável de ambiente para não vazá-la no código:

<CodeGroup>
  ```bash macOS / Linux theme={null}
  export LIQUERAPAY_API_KEY="liq_..."
  ```

  ```powershell Windows (PowerShell) theme={null}
  $env:LIQUERAPAY_API_KEY = "liq_..."
  ```
</CodeGroup>

## 2. Crie um cliente (opcional)

Cadastrar o cliente antes facilita identificá-lo nas cobranças:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.liquerapay.com/customers \
    -H "Authorization: Bearer $LIQUERAPAY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "email": "joao@exemplo.com",
      "name": "João Silva",
      "taxId": "12345678900"
    }'
  ```

  ```javascript Node.js (fetch) theme={null}
  const res = await fetch('https://api.liquerapay.com/customers', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LIQUERAPAY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email: 'joao@exemplo.com',
      name: 'João Silva',
      taxId: '12345678900',
    }),
  })

  const { data: customer } = await res.json()
  console.log(customer.id)
  ```

  ```python Python (requests) theme={null}
  import os, requests

  res = requests.post(
      "https://api.liquerapay.com/customers",
      headers={"Authorization": f"Bearer {os.environ['LIQUERAPAY_API_KEY']}"},
      json={
          "email": "joao@exemplo.com",
          "name": "João Silva",
          "taxId": "12345678900",
      },
  )
  customer = res.json()["data"]
  print(customer["id"])
  ```
</CodeGroup>

## 3. Crie uma cobrança PIX (Checkout Transparente)

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.liquerapay.com/transparents/create \
    -H "Authorization: Bearer $LIQUERAPAY_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "PIX",
      "amount": 5000,
      "description": "Pedido #1234",
      "customerId": "cust_018f3a2b7c4d7c40a1b2",
      "expiresIn": 1800
    }'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://api.liquerapay.com/transparents/create', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.LIQUERAPAY_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      method: 'PIX',
      amount: 5000,
      description: 'Pedido #1234',
      customerId: 'cust_018f3a2b7c4d7c40a1b2',
      expiresIn: 1800,
    }),
  })

  const { data: charge } = await res.json()
  console.log(charge.brCode)       // string copia-e-cola
  console.log(charge.imageBase64)  // PNG base64 para renderizar
  ```
</CodeGroup>

A resposta traz o **QR Code** pronto para apresentar:

```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",
    "createdAt": "2026-04-19T18:32:11.420Z"
  },
  "error": null,
  "success": true
}
```

## 4. Teste o pagamento

Não há ambiente de sandbox — para ver o fluxo completo de ponta a ponta,
pague o QR Code gerado com um **PIX real de baixo valor** (ex.: R\$ 0,50).
Depois de pago, você pode:

* Consultar o status com [`GET /transparents/check?id=...`](/pages/transparents/get)
* Devolver o valor com [`POST /transparents/refund?id=...`](/pages/transparents/refund-create)
* Ou, melhor ainda, [cadastrar um webhook](/pages/webhooks/reference) e
  receber o evento `CHARGE_PAID` automaticamente assim que o pagamento cair.

## 5. Próximos passos

<CardGroup cols={2}>
  <Card title="Checkout Transparente" icon="qrcode" href="/pages/start/checkout-transparente">
    Entenda o fluxo completo de criação, consulta e devolução de cobranças.
  </Card>

  <Card title="Configurar webhooks" icon="webhook" href="/pages/webhooks/reference">
    Receba os eventos no seu backend e processe pedidos automaticamente.
  </Card>
</CardGroup>