Listar transações

curl -X GET "https://api.chargefy.io/v1/transactions?status=pending&limit=2" \
  -H "Authorization: Bearer {{API_KEY}}"

{
  "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"
}

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

string

Filtra pelo tipo do movimento: charge, refund, chargefy_fee, platform_fee ou adjustment. Valor fora dessa lista responde 400.

string

Filtra pelo status: pending, paid, canceled ou refunded.

string

Todos os movimentos originados por um pagamento (pi_) — as parcelas, as taxas e os estornos dele.

string

Movimentos de uma cobrança específica (ch_).

string

Movimentos de um objeto causador exato: uma cobrança (ch_) ou um reembolso (re_).

object

Intervalo de criação: created_at[gte], created_at[gt], created_at[lte], created_at[lt]. Aceita ISO 8601 ou epoch em segundos.

object

Intervalo da previsão de liquidação, mesmos operadores. Use para montar o fluxo de caixa futuro.

object

Intervalo da liquidação real, mesmos operadores. Use para fechar um período já liquidado.

integer

default:"10"

Quantidade por página. Valores fora de 1–100 são ajustados para o limite mais próximo.

string

Cursor: retorna a página seguinte a esta transaction.

string

Cursor: retorna a página anterior a esta transaction.

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.

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.

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.

curl -X GET "https://api.chargefy.io/v1/transactions?status=pending&limit=2" \
  -H "Authorization: Bearer {{API_KEY}}"

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.

{
  "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"
}

Erros comuns

400

{
  "error": {
    "code": "invalid_request",
    "message": "type is invalid",
    "param": "type",
    "type": "invalid_request_error"
  }
}

400

{
  "error": {
    "code": "invalid_request",
    "message": "starting_after is not a valid transaction id",
    "param": "starting_after",
    "type": "invalid_request_error"
  }
}

400

{
  "error": {
    "code": "invalid_request",
    "message": "created_at[gte] must be a valid timestamp",
    "param": "created_at[gte]",
    "type": "invalid_request_error"
  }
}

curl -X GET "https://api.chargefy.io/v1/transactions?status=pending&limit=2" \
  -H "Authorization: Bearer {{API_KEY}}"

{
  "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"
}

Fundamentos da API

Objetos de sistema

Webhooks e eventos

SDKs

MCP

Listar transações

Autenticação

Parâmetros de query

Paginação

Resposta

Erros comuns

​Autenticação

​Parâmetros de query

​Paginação

​Resposta

​Erros comuns

Autenticação

Parâmetros de query

Paginação

Resposta

Erros comuns