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

# Listar transações

> Lista os movimentos do extrato.

Lista os movimentos do extrato, do mais recente para o mais antigo, com
paginação por cursor. É o endpoint de conciliação: somar `net_amount` de uma
página filtrada é somar o extrato, porque os movimentos de saída já vêm
negativos e entram na soma sem tratamento especial.

## Autenticação

| Credencial             | Acesso                                                                 |
| ---------------------- | ---------------------------------------------------------------------- |
| API key da organização | Movimentos da própria organização da key.                              |
| API key da plataforma  | Movimentos da organização conectada indicada no header `Organization`. |

Escopo `read` é suficiente. A listagem respeita o modo da chave: uma key de
produção nunca retorna movimentos de sandbox, e vice-versa.

## Parâmetros de query

<ParamField query="type" type="string">
  Filtra pelo tipo do movimento: `charge`, `refund`, `chargefy_fee`,
  `platform_fee` ou `adjustment`. Valor fora dessa lista responde `400`.
</ParamField>

<ParamField query="status" type="string">
  Filtra pelo status: `pending`, `paid`, `canceled` ou `refunded`.
</ParamField>

<ParamField query="payment_intent" type="string">
  Todos os movimentos originados por um pagamento (`pi_`) — as parcelas, as
  taxas e os estornos dele.
</ParamField>

<ParamField query="charge" type="string">
  Movimentos de uma cobrança específica (`ch_`).
</ParamField>

<ParamField query="source" type="string">
  Movimentos de um objeto causador exato: uma cobrança (`ch_`) ou um reembolso
  (`re_`).
</ParamField>

<ParamField query="created_at" type="object">
  Intervalo de criação: `created_at[gte]`, `created_at[gt]`, `created_at[lte]`,
  `created_at[lt]`. Aceita ISO 8601 ou epoch em segundos.
</ParamField>

<ParamField query="available_at" type="object">
  Intervalo da previsão de liquidação, mesmos operadores. Use para montar o
  fluxo de caixa futuro.
</ParamField>

<ParamField query="settled_at" type="object">
  Intervalo da liquidação real, mesmos operadores. Use para fechar um período já
  liquidado.
</ParamField>

<ParamField query="limit" type="integer" default="10">
  Quantidade por página. Valores fora de 1–100 são ajustados para o limite mais
  próximo.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor: retorna a página seguinte a esta transaction.
</ParamField>

<ParamField query="ending_before" type="string">
  Cursor: retorna a página anterior a esta transaction.
</ParamField>

Os filtros são combináveis e se acumulam com `AND`. Só existem igualdade e os
operadores de intervalo acima — não há `[in]`, `[ne]` nem busca textual.

<Tip>
  Para fechar um mês já liquidado, combine status e intervalo:
  `?status=paid&settled_at[gte]=2026-07-01T00:00:00Z&settled_at[lt]=2026-08-01T00:00:00Z`.
  Some `net_amount` de todas as páginas e você tem o líquido do período.
</Tip>

## Paginação

A ordenação é por `created_at` decrescente, e os cursores caminham nessa mesma
ordem. Passe o `id` da última transaction da página em `starting_after` para
pedir a próxima e use `has_more` para saber quando parar. O cursor precisa ser
um `txn_` visível para a sua key — um id inexistente, de outra organização ou
do outro modo responde `400`.

<RequestExample>
  ```bash cURL theme={"theme":"css-variables"}
  curl -X GET "https://api.chargefy.io/v1/transactions?status=pending&limit=2" \
    -H "Authorization: Bearer {{API_KEY}}"
  ```
</RequestExample>

## Resposta

`200 OK` com o envelope de listagem. `data` traz objetos `transaction`
completos — nunca uma versão resumida. Lista vazia retorna o mesmo envelope com
`data: []`, nunca `404`.

<ResponseExample>
  ```json Resposta theme={"theme":"css-variables"}
  {
    "object": "list",
    "data": [
      {
        "id": "txn_nGT91yqbix7QcRLu",
        "object": "transaction",
        "amount": 11000,
        "available_at": "2026-09-19T00:00:00Z",
        "created_at": "2026-07-20T14:32:11Z",
        "currency": "brl",
        "description": "Installment 2/10",
        "fee_amount": 1399,
        "fee_details": [
          {
            "amount": 1000,
            "description": "Installment interest",
            "type": "installment_interest"
          },
          {
            "amount": 399,
            "description": "Chargefy processing fee",
            "type": "chargefy_fee"
          }
        ],
        "installment": 2,
        "installment_count": 10,
        "livemode": true,
        "metadata": {},
        "net_amount": 9601,
        "payment_intent": "pi_WR9zovL9PaPMUFnb",
        "settled_at": null,
        "source": "ch_jecXa7hAhsBgvDbD",
        "status": "pending",
        "type": "charge",
        "updated_at": null
      },
      {
        "id": "txn_8gFmBCVXBi1pgYJz",
        "object": "transaction",
        "amount": -11000,
        "available_at": null,
        "created_at": "2026-07-19T09:14:03Z",
        "currency": "brl",
        "description": "Refund",
        "fee_amount": 0,
        "fee_details": [],
        "installment": null,
        "installment_count": null,
        "livemode": true,
        "metadata": {},
        "net_amount": -11000,
        "payment_intent": "pi_WR9zovL9PaPMUFnb",
        "settled_at": "2026-07-19T09:14:03Z",
        "source": "re_hFYkHp6h9kBLBHLS",
        "status": "paid",
        "type": "refund",
        "updated_at": "2026-07-19T09:14:03Z"
      }
    ],
    "has_more": true,
    "url": "/v1/transactions"
  }
  ```
</ResponseExample>

## Erros comuns

```json 400 theme={"theme":"css-variables"}
{
  "error": {
    "code": "invalid_request",
    "message": "type is invalid",
    "param": "type",
    "type": "invalid_request_error"
  }
}
```

```json 400 theme={"theme":"css-variables"}
{
  "error": {
    "code": "invalid_request",
    "message": "starting_after is not a valid transaction id",
    "param": "starting_after",
    "type": "invalid_request_error"
  }
}
```

```json 400 theme={"theme":"css-variables"}
{
  "error": {
    "code": "invalid_request",
    "message": "created_at[gte] must be a valid timestamp",
    "param": "created_at[gte]",
    "type": "invalid_request_error"
  }
}
```