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

# Listar cobranças

> Lista as cobranças da conta, da mais recente para a mais antiga.

<Note>
  Filtrar por `reference` é o caminho para reencontrar uma cobrança sem guardar o `id` que devolvemos.
  O laço de paginação completo está em [Conciliar cobranças com os seus pedidos](/receitas/conciliacao).
</Note>


## OpenAPI

````yaml api-reference/openapi.yaml GET /v1/charges
openapi: 3.1.0
info:
  title: Vext - API de pagamentos PIX com split
  version: 1.0.0
  summary: Cobranças PIX, estornos e saldo do vendedor.
  description: |
    API pública do gateway. Todo endpoint desta versão vive sob `/v1`.

    Quatro regras valem para toda chamada. Cada uma tem uma página própria
    nos guias, com exemplos nas quatro linguagens.

    - **Dinheiro é sempre centavos inteiros.** R$ 100,00 se envia como
      `10000`; um decimal devolve `422`. Ver
      [Valores em centavos](/essenciais/valores-em-centavos).
    - **A chave secreta vai no header e fica no servidor.** Cada chave
      carrega escopos; fora do escopo devolve `403`, e não `401`. Ver
      [Autenticação](/essenciais/autenticacao).
    - **Envie `Idempotency-Key` em todo `POST`.** Repetir com a mesma chave
      devolve a resposta gravada em vez de criar um segundo recurso. Ver
      [Idempotência](/essenciais/idempotencia).
    - **Trate os erros pelo `code`**, nunca pela `message` - o código é
      contrato, o texto pode ser reescrito a qualquer momento. Ver
      [Erros](/essenciais/erros).
  contact:
    name: Suporte Vext
    email: suporte@usevext.com
servers:
  - url: https://api.usevext.com
    description: Produção
security:
  - apiKey: []
tags:
  - name: Cobranças
    description: Criação, consulta e estorno de cobranças PIX.
  - name: Saldo
    description: Quanto o vendedor tem e quanto pode sacar.
paths:
  /v1/charges:
    get:
      tags:
        - Cobranças
      summary: Listar cobranças
      description: |
        Lista as cobranças da conta, da mais recente para a mais antiga.
        Apenas as cobranças do vendedor dono da chave - não existe forma de
        alcançar a venda de outra conta por esta API.
      operationId: listCharges
      parameters:
        - name: status
          in: query
          description: Filtra por situação.
          schema:
            $ref: '#/components/schemas/ChargeStatus'
        - name: reference
          in: query
          description: |
            Sua referência, exatamente como enviada em `reference` na
            criação. É o caminho para reencontrar uma cobrança sem guardar
            o `id` que devolvemos.
          schema:
            type: string
            maxLength: 120
          example: pedido-1042
        - name: created_from
          in: query
          description: Criadas a partir desta data e hora (ISO 8601).
          schema:
            type: string
            format: date-time
          example: '2026-08-01T00:00:00-03:00'
        - name: created_to
          in: query
          description: Criadas até esta data e hora (ISO 8601).
          schema:
            type: string
            format: date-time
          example: '2026-08-31T23:59:59-03:00'
        - name: per_page
          in: query
          description: |
            Itens por página. O teto de 100 existe porque uma página gigante
            de um vendedor com histórico degrada a consulta para todos os
            outros.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 25
        - name: page
          in: query
          schema:
            type: integer
            minimum: 1
            default: 1
      responses:
        '200':
          description: Página de cobranças.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChargeList'
              examples:
                pagina:
                  summary: Primeira página
                  value:
                    object: list
                    data:
                      - object: charge
                        id: ch_01k1y6r6m6q2x0p3d9v4t7c8n2
                        status: paid
                        payment_method: pix
                        amount: 10000
                        currency: BRL
                        platform_fee: 798
                        net_amount: 9202
                        refunded_amount: 0
                        description: Curso de Vue 3
                        reference: pedido-1042
                        customer:
                          name: João Comprador
                          email: joao@exemplo.com.br
                          document: 111.***.***-35
                        pix:
                          qr_code: >-
                            00020101021226840014br.gov.bcb.pix2562qrcodepix.example.com/v2/abcd1234
                          expires_at: '2026-08-04T15:00:00+00:00'
                          end_2_end_id: E12345678202608041200
                        created_at: '2026-08-04T14:00:00+00:00'
                        paid_at: '2026-08-04T14:03:11+00:00'
                        expired_at: null
                        refunded_at: null
                    pagination:
                      page: 1
                      per_page: 25
                      total: 1
                      total_pages: 1
                      has_more: false
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/ValidationFailed'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
      security:
        - apiKey:
            - charges:read
components:
  schemas:
    ChargeStatus:
      type: string
      description: |
        Situação da cobrança. Todos os estados exceto `pending` são
        terminais - exceto os que ainda admitem estorno.

        `partially_refunded` é estado próprio, e não um `refunded` com
        asterisco: tratar uma venda devolvida pela metade como estornada
        faria seu relatório descontar o valor inteiro.
      enum:
        - pending
        - paid
        - expired
        - canceled
        - partially_refunded
        - refunded
        - failed
      x-labels:
        pending: Aguardando pagamento
        paid: Pago
        expired: Expirado
        canceled: Cancelado
        partially_refunded: Estornado em parte
        refunded: Estornado
        failed: Falhou
    ChargeList:
      type: object
      required:
        - object
        - data
        - pagination
      properties:
        object:
          type: string
          const: list
        data:
          type: array
          items:
            $ref: '#/components/schemas/Charge'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Charge:
      type: object
      required:
        - object
        - id
        - status
        - payment_method
        - amount
        - currency
      properties:
        object:
          type: string
          const: charge
        id:
          type: string
          description: |
            Código público da cobrança. Nunca é a chave primária: expor o
            autoincremento diria a qualquer cliente quantas vendas a
            plataforma inteira processou.
          example: ch_01k1y6r6m6q2x0p3d9v4t7c8n2
        status:
          $ref: '#/components/schemas/ChargeStatus'
        payment_method:
          type: string
          enum:
            - pix
        amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: Valor cobrado, em centavos inteiros.
        currency:
          type: string
          const: BRL
        platform_fee:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Nossa taxa, em centavos inteiros. Congelada na criação: reflete
            o contrato que valia quando a venda aconteceu, não o de hoje.
        net_amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            O que fica com o vendedor, em centavos inteiros
            (`amount - platform_fee`).
        refunded_amount:
          allOf:
            - $ref: '#/components/schemas/Cents'
          description: |
            Total já devolvido ao comprador, em centavos inteiros. Acumulado
            entre estornos parciais.
        description:
          type:
            - string
            - 'null'
        reference:
          type:
            - string
            - 'null'
        customer:
          $ref: '#/components/schemas/CustomerSummary'
        pix:
          type: object
          properties:
            qr_code:
              type:
                - string
                - 'null'
              description: |
                Payload copia-e-cola do PIX. Gere a imagem do QR a partir
                dele - não devolvemos PNG.
            expires_at:
              type:
                - string
                - 'null'
              format: date-time
            end_2_end_id:
              type:
                - string
                - 'null'
              description: |
                Identificador da transação no Sistema de Pagamentos
                Brasileiro. Aparece depois do pagamento e é o que o banco do
                comprador reconhece.
        created_at:
          type:
            - string
            - 'null'
          format: date-time
        paid_at:
          type:
            - string
            - 'null'
          format: date-time
        expired_at:
          type:
            - string
            - 'null'
          format: date-time
        refunded_at:
          type:
            - string
            - 'null'
          format: date-time
    Pagination:
      type: object
      required:
        - page
        - per_page
        - total
        - total_pages
        - has_more
      properties:
        page:
          type: integer
        per_page:
          type: integer
        total:
          type: integer
        total_pages:
          type: integer
        has_more:
          type: boolean
          description: Há página seguinte?
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - type
            - code
            - message
            - details
          properties:
            type:
              type: string
              description: |
                Família do erro. Responde "de quem é o problema e o que
                fazer": `invalid_request_error` se corrige mudando a
                chamada, `authentication_error` trocando a chave, e
                `api_error` é nosso - repita, não reescreva.
              enum:
                - authentication_error
                - permission_error
                - invalid_request_error
                - idempotency_error
                - not_found_error
                - rate_limit_error
                - api_error
            code:
              type: string
              description: |
                Código estável do erro. **Trate por ele.** A `message` pode
                ser reescrita a qualquer momento; o código, não.
            message:
              type: string
              description: Explicação em português, para leitura humana.
            details:
              type: object
              description: |
                Sempre objeto, mesmo vazio. Em `validation_failed`, traz os
                campos recusados e suas mensagens.
              additionalProperties: true
    Cents:
      type: integer
      format: int64
      description: |
        Valor monetário em **centavos inteiros** de real. R$ 10,00 = `1000`.
        Nunca decimal, nunca string.
    CustomerSummary:
      type: object
      description: O comprador, como devolvemos.
      properties:
        name:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
        document:
          type:
            - string
            - 'null'
          description: |
            Mascarado. Você já enviou o documento; devolvê-lo inteiro em
            toda consulta espalharia o dado sem nenhum ganho.
          example: 111.***.***-35
  responses:
    Unauthorized:
      description: |
        Chave ausente, desconhecida, revogada ou expirada. A revogada é
        distinguida da inexistente na MENSAGEM, nunca no status: quem
        integra precisa saber que a chave existiu e foi desligada, e quem
        está adivinhando tokens não aprende nada com isso.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ausente:
              summary: missing_api_key
              value:
                error:
                  type: authentication_error
                  code: missing_api_key
                  message: 'Envie a chave em Authorization: Bearer sk_live_...'
                  details: {}
            invalida:
              summary: invalid_api_key
              value:
                error:
                  type: authentication_error
                  code: invalid_api_key
                  message: Chave de API inválida.
                  details: {}
            revogada:
              summary: revoked_api_key
              value:
                error:
                  type: authentication_error
                  code: revoked_api_key
                  message: >-
                    Esta chave de API foi revogada. Gere uma nova em
                    Desenvolvedores.
                  details: {}
            expirada:
              summary: expired_api_key
              value:
                error:
                  type: authentication_error
                  code: expired_api_key
                  message: Esta chave de API expirou. Gere uma nova em Desenvolvedores.
                  details: {}
    Forbidden:
      description: |
        A chave é válida, mas não tem o escopo do endpoint. `403` e não
        `401` de propósito: `401` diria "sua chave está errada" a quem tem
        a chave certa.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            escopo:
              summary: insufficient_scope
              value:
                error:
                  type: permission_error
                  code: insufficient_scope
                  message: Esta chave não tem o escopo [refunds:write].
                  details:
                    required_ability: refunds:write
                    abilities:
                      - charges:read
                      - charges:write
    ValidationFailed:
      description: Campos inválidos.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            validacao:
              value:
                error:
                  type: invalid_request_error
                  code: validation_failed
                  message: Alguns campos não passaram na validação.
                  details:
                    amount:
                      - >-
                        O valor deve ser um inteiro em centavos (R$ 10,00 =
                        1000).
    RateLimited:
      description: |
        Requisições demais.

        Há três limites, por minuto: um por IP antes da autenticação, e
        depois um de leitura e um de escrita, ambos por CHAVE - o excesso
        de uma integração não consome a cota das outras do mesmo
        vendedor. A escrita é bem mais apertada porque cada cobrança
        criada vira uma chamada ao provedor.

        `Retry-After` diz em quantos segundos voltar. Os cabeçalhos
        `X-RateLimit-*` vêm em TODA resposta, não só nesta: são eles que
        permitem desacelerar antes de bater no limite.
      headers:
        Retry-After:
          description: Segundos até a cota ser reposta.
          schema:
            type: integer
        X-RateLimit-Limit:
          description: Requisições permitidas por minuto neste balde.
          schema:
            type: integer
        X-RateLimit-Remaining:
          description: Quantas ainda cabem no minuto corrente.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            cota:
              summary: too_many_requests
              value:
                error:
                  type: rate_limit_error
                  code: too_many_requests
                  message: Muitas requisições. Tente novamente em 42 segundos.
                  details:
                    retry_after: 42
            provedor:
              summary: provider_rate_limited
              value:
                error:
                  type: rate_limit_error
                  code: provider_rate_limited
                  message: >-
                    Limite de requisições do provedor atingido. Tente novamente
                    em instantes.
                  details: {}
    InternalError:
      description: |
        Erro inesperado do nosso lado. Repita com a mesma
        `Idempotency-Key` - ela é o que torna repetir seguro.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            interno:
              value:
                error:
                  type: api_error
                  code: internal_error
                  message: >-
                    Erro interno. Se persistir, informe o horário da chamada ao
                    suporte.
                  details: {}
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: sk_live_… | sk_test_…
      description: |
        Chave secreta do vendedor, criada no painel em **Desenvolvedores**.

        O valor em claro existe uma única vez, na criação. Guardamos só o
        hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto:
        um dump do nosso banco não permite cobrar em nome de ninguém.

        A chave vai no **servidor**. Colocá-la no navegador do comprador a
        entrega a qualquer pessoa que abra a página.

````