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

# Listar extrato

> Retorna as transações que movimentaram o saldo da conta, da mais recente para a mais antiga. Cada item traz as movimentações geradas pela transação, como a entrada do valor e a saída da taxa.

Sem `status`, transações `PENDING` ficam de fora. Sem `kind`, movimentações internas que não alteram o saldo disponível ficam de fora. Informar um desses filtros substitui a regra padrão correspondente.


Retorna todas as transações que movimentaram o saldo da sua conta, da mais recente para a mais antiga.

<Card horizontal>
  Requer a permissão `BANK_STATEMENT:READ`.
</Card>

Use `limit`, `after` e `before` para paginar e `startDate`/`endDate` (`YYYY-MM-DD`) para filtrar por data de criação. Consulte [Paginação e filtro por data](/pages/reference/introduction#paginação-e-filtro-por-data). O formato de cada item está na [referência do extrato](/pages/bank-statement/reference).

Os filtros `status`, `method` e `kind` aceitam um valor por vez e se aplicam à transação, não às movimentações dentro dela.

<Warning>
  Sem `status`, o extrato esconde transações `PENDING`. Sem `kind`, esconde movimentações internas que não alteram o saldo disponível. Ao informar um desses filtros, a regra padrão correspondente deixa de valer: `status=PENDING`, por exemplo, retorna as transações pendentes.
</Warning>


## OpenAPI

````yaml GET /bank-statement/list
openapi: 3.1.0
info:
  title: API AbacatePay
  description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay.
  version: 1.0.0
servers:
  - url: https://api.abacatepay.com/v2
    description: Único servidor para os ambientes de produção e sandbox.
security: []
paths:
  /bank-statement/list:
    get:
      summary: Listar extrato
      description: >
        Retorna as transações que movimentaram o saldo da conta, da mais recente
        para a mais antiga. Cada item traz as movimentações geradas pela
        transação, como a entrada do valor e a saída da taxa.


        Sem `status`, transações `PENDING` ficam de fora. Sem `kind`,
        movimentações internas que não alteram o saldo disponível ficam de fora.
        Informar um desses filtros substitui a regra padrão correspondente.
      parameters:
        - $ref: '#/components/parameters/QueryAfter'
        - $ref: '#/components/parameters/QueryBefore'
        - $ref: '#/components/parameters/QueryLimit'
        - $ref: '#/components/parameters/QueryStartDate'
        - $ref: '#/components/parameters/QueryEndDate'
        - name: status
          in: query
          description: Filtrar pelo status da transação.
          required: false
          schema:
            type: string
            enum:
              - PENDING
              - APPROVED
              - EXPIRED
              - CANCELLED
              - COMPLETE
              - REFUNDED
              - REDEEMED
              - UNDER_DISPUTE
              - FAILED
            example: COMPLETE
        - name: method
          in: query
          description: Filtrar pelo meio da transação.
          required: false
          schema:
            type: string
            enum:
              - PIX
              - PIX_QRCODE
              - CARD
              - BOLETO
              - TED
              - INTERNAL
            example: PIX
        - name: kind
          in: query
          description: >-
            Filtrar pelo tipo da transação. Os mais comuns são `DEPOSIT`
            (pagamento recebido), `WITHDRAW` (saque ou PIX enviado), `REFUND`
            (estorno), `CARD_APPROVED` (recebível de cartão aprovado),
            `SWAP_INTERNAL_CREDIT_CARD_RECEIVED` (liquidação do cartão),
            `ANTICIPATION_CREDITED` (antecipação creditada) e `PLUGIN_FEE` (taxa
            de plugin).
          required: false
          schema:
            type: string
            example: DEPOSIT
        - name: search
          in: query
          description: >-
            Busca pelo ID da transação. Aceita parte do ID e não diferencia
            maiúsculas de minúsculas.
          required: false
          schema:
            type: string
            example: tran_abc123
      responses:
        '200':
          description: Extrato retornado com sucesso.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    description: Transações do extrato.
                    items:
                      $ref: '#/components/schemas/BankStatementItem'
                  success:
                    $ref: '#/components/schemas/Success'
                  error:
                    type: string
                    nullable: true
                    example: null
                  pagination:
                    $ref: '#/components/schemas/PaginationCursor'
        '401':
          description: Não autorizado. Falha na autenticação.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: >-
                      Mensagem de erro descrevendo o motivo da falha na
                      autenticação.
                    example: Token de autenticação inválido ou ausente.
      security:
        - bearerAuth: []
components:
  parameters:
    QueryAfter:
      name: after
      in: query
      description: >-
        Cursor para buscar itens após este ponto (use o `publicId` retornado em
        `pagination.next`).
      required: false
      schema:
        type: string
    QueryBefore:
      name: before
      in: query
      description: >-
        Cursor para buscar itens antes deste ponto (use o `publicId` retornado
        em `pagination.before`).
      required: false
      schema:
        type: string
    QueryLimit:
      name: limit
      in: query
      description: Quantidade de itens por página (1-100).
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
        example: 100
    QueryStartDate:
      name: startDate
      in: query
      description: >
        Filtra registros criados a partir desta data (inclusive). Formato
        `YYYY-MM-DD`. O intervalo é interpretado no fuso horário
        `America/Sao_Paulo` (00:00 do dia inicial).
      required: false
      schema:
        type: string
        format: date
        example: '2026-01-01'
    QueryEndDate:
      name: endDate
      in: query
      description: >
        Filtra registros criados até esta data (inclusive). Formato
        `YYYY-MM-DD`. O intervalo é interpretado no fuso horário
        `America/Sao_Paulo` (23:59:59.999 do dia final).
      required: false
      schema:
        type: string
        format: date
        example: '2026-01-31'
  schemas:
    BankStatementItem:
      type: object
      description: Transação do extrato com as movimentações de saldo que ela gerou.
      additionalProperties: false
      required:
        - id
        - movements
        - currency
        - createdAt
        - checkoutId
        - paymentIntentId
        - referenceId
        - customer
      properties:
        id:
          type: string
          description: ID da transação na AbacatePay.
          example: tran_abc123xyz
        movements:
          type: array
          description: >-
            Movimentações de saldo geradas pela transação. Um pagamento recebido
            gera a entrada do valor e a saída da taxa.
          items:
            $ref: '#/components/schemas/BankStatementMovement'
        currency:
          type: string
          description: Moeda da transação.
          example: BRL
        createdAt:
          type: string
          format: date-time
          description: Data/hora de criação (ISO 8601).
          example: '2026-09-29T14:32:10.000Z'
        checkoutId:
          type: string
          nullable: true
          description: >-
            Checkout de origem, quando a transação veio de um pagamento. `null`
            em saques.
          example: bill_abc123xyz
        paymentIntentId:
          type: string
          nullable: true
          description: Cobrança de origem, quando existe. `null` em saques.
          example: char_abc123xyz
        referenceId:
          type: string
          nullable: true
          description: 'O `externalId` informado ao criar a operação (ex.: um saque ou PIX).'
          example: null
        customer:
          type: object
          nullable: true
          description: >-
            Cliente vinculado à cobrança. Sem cliente cadastrado, traz apenas
            `name` e `taxId` de quem pagou. `null` quando não há nenhum dado.
          additionalProperties: false
          properties:
            publicId:
              type: string
              description: ID do cliente na AbacatePay.
              example: cust_abc123xyz
            name:
              type: string
              example: Maria Silva
            email:
              type: string
              example: maria@exemplo.com
            taxId:
              type: string
              description: CPF ou CNPJ.
              example: 123.456.789-01
            cellphone:
              type: string
              example: (11) 99999-9999
            zipCode:
              type: string
              example: 01310-100
    Success:
      type: boolean
      description: Se a requisição obteve sucesso ou não.
      example: true
    PaginationCursor:
      type: object
      description: Informações de paginação baseada em cursor.
      required:
        - hasMore
        - next
        - before
      additionalProperties: false
      properties:
        hasMore:
          type: boolean
          description: Indica se existe mais itens para carregar.
        next:
          type: string
          nullable: true
          description: Cursor para próxima página (usar em after).
        before:
          type: string
          nullable: true
          description: Cursor para página anterior (usar em before).
    BankStatementMovement:
      type: object
      description: Uma movimentação de saldo dentro de uma transação do extrato.
      additionalProperties: false
      required:
        - amount
        - kind
        - method
        - description
        - category
        - balanceEffect
      properties:
        amount:
          type: integer
          description: >-
            Valor em centavos, sempre positivo. O sentido vem de
            `balanceEffect`.
          example: 10000
        kind:
          type: string
          description: 'Tipo da movimentação (ex.: `DEPOSIT`, `WITHDRAW`, `CARD_APPROVED`).'
          example: DEPOSIT
        method:
          type: string
          enum:
            - PIX
            - PIX_QRCODE
            - CARD
            - BOLETO
            - TED
            - INTERNAL
          example: PIX
        description:
          type: string
          description: Descrição legível, a mesma exibida no dashboard.
          example: Pagamento PIX
        category:
          type: string
          enum:
            - transaction
            - withdrawal
            - refund
            - fee
            - reversal
          description: >-
            `transaction` para entradas e movimentações de pagamento,
            `withdrawal` para saques e PIX enviados, `refund` para estornos,
            `fee` para taxas e `reversal` para desfazimentos.
          example: transaction
        balanceEffect:
          type: string
          enum:
            - credit
            - debit
            - none
          description: >-
            Efeito no saldo disponível. `none` aparece no recebível de cartão
            aprovado, que só entra no saldo disponível na liquidação.
          example: credit
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        Todas as requisições devem incluir sua chave de API no header
        Authorization usando o formato `Bearer <abacatepay-api-key>`. Sem esse
        header a requisição será rejeitada.


        Saiba mais sobre como criar e usar chaves de API na [documentação de
        autenticação](/pages/authentication).

````