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

# Consultar Cobrança

> Recupere uma cobrança pelo uuid, incluindo status e dados de pagamento

## Visão Geral

Retorna uma cobrança da sua conta pelo `uuid`. Use para acompanhar o status de um pagamento — especialmente num [checkout transparente](/guias/checkout-transparente), enquanto o cliente ainda não pagou o PIX ou o boleto.

<Tip>
  Para saber de um pagamento **assim que ele acontece**, prefira [webhooks](/api-reference/webhooks) em vez de ficar consultando este endpoint em loop.
</Tip>

## Headers

<ParamField header="Authorization" type="string" required>
  Sua chave de API (`Bearer sk_live_...`)
</ParamField>

## Path Parameters

<ParamField path="uuid" type="string" required>
  UUID da cobrança, devolvido na criação
</ParamField>

## Exemplo de Requisição

<CodeGroup>
  ```bash cURL theme={null}
  curl https://garu.com.br/api/v1/charges/6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f \
    -H "Authorization: Bearer sk_live_sua_chave_api"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    `https://garu.com.br/api/v1/charges/${chargeUuid}`,
    { headers: { Authorization: `Bearer ${process.env.GARU_API_KEY}` } }
  );

  const charge = await response.json();
  console.log(charge.status);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      f"https://garu.com.br/api/v1/charges/{charge_uuid}",
      headers={"Authorization": f"Bearer {os.environ['GARU_API_KEY']}"},
  )

  print(response.json()["status"])
  ```
</CodeGroup>

## Resposta de Sucesso (200 OK)

```json theme={null}
{
  "uuid": "6f1c9b2e-4a7d-4f0b-9a3e-1d2c3b4a5e6f",
  "status": "paid",
  "paymentMethod": "pix",
  "amount": 349.00,
  "chargedTotal": 349.00,
  "installments": 1,
  "product": {
    "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Curso de Marketing Digital"
  },
  "customer": {
    "name": "Maria Silva",
    "email": "maria@exemplo.com.br",
    "document": "***456789**"
  },
  "pix": { "code": "00020101021226840014br.gov.bcb.pix..." },
  "boleto": null,
  "card": null,
  "refund": null,
  "createdAt": "2026-07-22T14:03:11.000Z",
  "expiresAt": null
}
```

<Note>
  Bandeira e últimos 4 dígitos do cartão só vêm na **resposta da criação**. Numa consulta posterior o bloco `card` volta com os campos nulos.
</Note>

## Status possíveis

O `status` é um valor **estável e amigável** — o mesmo para PIX, boleto e cartão. Você pode ramificar com segurança nele (`if (charge.status === 'paid')`); ele não muda se trocarmos de adquirente por trás.

| Status           | Descrição                                                   | Pago?   |
| ---------------- | ----------------------------------------------------------- | ------- |
| `pending`        | Aguardando o pagamento do cliente (PIX ou boleto em aberto) | Não     |
| `authorized`     | Cartão autorizado, valor ainda não capturado                | Não     |
| `paid`           | Pagamento confirmado — pode liberar o produto               | **Sim** |
| `failed`         | Pagamento negado ou indisponível                            | Não     |
| `expired`        | Boleto venceu sem pagamento                                 | Não     |
| `canceled`       | Cobrança cancelada antes do pagamento                       | Não     |
| `refund_pending` | Estorno de PIX solicitado, aguardando a devolução liquidar  | Não     |
| `refunded`       | Valor devolvido ao cliente                                  | Não     |
| `chargeback`     | Estorno forçado (contestação junto à bandeira)              | Não     |

<Tip>
  **Aja em `paid`.** É o único status que garante que o dinheiro entrou. `authorized` (cartão) ainda não é captura, e `refund_pending` significa que a devolução foi pedida mas ainda não caiu na conta do cliente.
</Tip>

## Erros

| Código | Quando acontece                                              |
| ------ | ------------------------------------------------------------ |
| `401`  | Chave de API ausente ou inválida                             |
| `404`  | A cobrança não existe ou não pertence à conta da chave usada |