> ## Documentation Index > Fetch the complete documentation index at: https://docs.gravitypay.app/llms.txt > Use this file to discover all available pages before exploring further. # Listar cobranças > Lista paginada das cobranças (vendas) da loja da chave. Todos os filtros são opcionais; sem filtro traz tudo. A chave é escopada a uma única loja. Cada item traz o `customer` completo (com endereço/CEP) e a `offer` detalhada — o valor cheio da oferta/lote, distinto de `amountInCents` (o valor pago, que pode ser uma parcela). Escopo exigido: `payments:read`. ## OpenAPI ````yaml /openapi.json get /v1/payments openapi: 3.1.0 info: title: Gravity Play API version: 1.0.0 description: >- API para criar cobranças, receber pagamentos e ler cursos, turmas, alunos e progresso da área de membros. Cada chave de API tem escopos; cada operação indica o escopo que exige. servers: - url: https://api.sandbox.gravitypay.app description: Sandbox (testes) — alvo do try-it - url: https://api.gravitypay.app description: Produção security: - bearerAuth: [] tags: - name: Cobranças description: Cobranças avulsas com link de pagamento. - name: Pagamentos description: Vendas da loja e vendedores. - name: Assinaturas description: Assinaturas da loja, com dados do cliente. Exige `subscriptions:read`. - name: Cursos description: Cursos da área de membros, com módulos e aulas. - name: Turmas description: Turmas dos cursos. - name: Alunos description: 'Alunos, matrículas e progresso. Dado pessoal: exige `students:read`.' paths: /v1/payments: get: tags: - Pagamentos summary: Listar cobranças description: >- Lista paginada das cobranças (vendas) da loja da chave. Todos os filtros são opcionais; sem filtro traz tudo. A chave é escopada a uma única loja. Cada item traz o `customer` completo (com endereço/CEP) e a `offer` detalhada — o valor cheio da oferta/lote, distinto de `amountInCents` (o valor pago, que pode ser uma parcela). Escopo exigido: `payments:read`. operationId: listPayments parameters: - name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: Página (começa em 1). - name: perPage in: query required: false schema: type: integer minimum: 1 maximum: 500 default: 500 description: Itens por página (máx. 500; default 500). - name: status in: query required: false schema: type: string enum: - PENDING - PAID - FAILED - REFUNDED - EXPIRED description: Filtra por status do pagamento. - name: productId in: query required: false schema: type: string description: Filtra os pagamentos de um produto. - name: startDate in: query required: false schema: type: string description: >- Início do período (filtra por createdAt). Aceita YYYY-MM-DD (início do dia, UTC) ou ISO 8601 completo. - name: endDate in: query required: false schema: type: string description: >- Fim do período (filtra por createdAt). YYYY-MM-DD é tratado como o FIM do dia (23:59:59.999 UTC), então o dia inteiro entra. - name: storeId in: query required: false schema: type: string description: >- Opcional. Se enviado, precisa ser o id da loja desta chave — não há agregação cross-store; um id diferente retorna 400. - name: salesRepId in: query required: false schema: type: string description: >- Filtra pelos pagamentos de um vendedor. Use o literal `none` para as vendas diretas (sem vendedor). Um id que não existe na loja da chave devolve lista vazia, sem erro. - name: salesRefCode in: query required: false schema: type: string description: >- Filtra pelo código de referência bruto gravado no pagamento (igualdade exata, sem normalizar caixa/espaço) — mesmo quando o código não resolveu para nenhum vendedor. - name: meta in: query required: false schema: type: string description: >- JSON de até 10 pares `{scope, key, value}`. `scope` é `metadata` ou `tracking`. `value` casa por igualdade exata. Vários pares combinam em AND. Exemplo: `[{"scope":"tracking","key":"utm_source","value":"facebook"}]`. description: >- Filtra por chave/valor dentro de metadata ou tracking (UTMs). Um par malformado, ou mais de 10 pares, responde 400 sem aplicar nenhum filtro de metadata. responses: '200': description: Lista de pagamentos content: application/json: schema: $ref: '#/components/schemas/PaymentList' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/InsufficientScope' components: schemas: PaymentList: type: object properties: object: type: string example: list data: type: array items: $ref: '#/components/schemas/Payment' page: type: integer perPage: type: integer total: type: integer description: Total de registros que casam com o filtro (ignora a paginação). totalPages: type: integer hasMore: type: boolean description: true se ainda há páginas seguintes. Payment: type: object properties: id: type: string example: clz8h2k9x0000ab12cd34ef56 object: type: string example: payment status: type: string enum: - PENDING - PAID - FAILED - REFUNDED - EXPIRED amountInCents: type: integer description: Valor bruto pago, em centavos. currency: type: string example: brl platformFeeInCents: type: integer description: Taxa da plataforma, em centavos. netInCents: type: integer description: Líquido estimado = amountInCents − platformFeeInCents. paymentMethod: type: string nullable: true enum: - pix - boleto - credit_card description: Meio de pagamento. Pode ser null enquanto não definido. provider: type: string example: PAGARME description: 'Gateway que processou (ex.: STRIPE, ASAAS, PAGARME, EFI, SICOOB).' product: type: object nullable: true description: Produto vinculado, quando houver. properties: id: type: string name: type: string nullable: true offerId: type: string nullable: true offer: type: object nullable: true description: >- Oferta detalhada (o "lote"). `priceInCents` é o valor CHEIO da oferta/produto — distinto de `amountInCents`, que é o valor pago (pode ser uma parcela). properties: id: type: string name: type: string description: type: string nullable: true billingType: type: string enum: - ONE_TIME - RECURRING billingCycle: type: string nullable: true description: WEEKLY, MONTHLY, YEARLY… (null em ONE_TIME). priceInCents: type: integer description: Valor cheio da oferta/produto. currency: type: string setupFeeInCents: type: integer nullable: true description: Taxa de adesão (1º ciclo). trialDays: type: integer nullable: true maxCharges: type: integer nullable: true statementDescriptor: type: string nullable: true product: type: object properties: id: type: string name: type: string subscriptionId: type: string nullable: true description: Preenchido quando o pagamento é a renovação de uma assinatura. chargeId: type: string nullable: true description: >- Preenchido quando a venda veio de uma cobrança avulsa (POST /v1/charges). customer: type: object properties: name: type: string nullable: true email: type: string nullable: true phone: type: string nullable: true document: type: string nullable: true description: CPF/CNPJ (apenas dígitos). address: type: object nullable: true description: 'Endereço de cobrança (cartão/boleto) ou null (ex.: PIX).' properties: zipCode: type: string description: CEP (apenas dígitos). street: type: string number: type: string complement: type: string nullable: true neighborhood: type: string city: type: string state: type: string description: UF (2 letras). externalId: type: string description: Id da transação no gateway (checkout session). storeId: type: string description: Id da loja (organization) — igual ao escopo da chave. metadata: type: object additionalProperties: true tracking: type: object nullable: true additionalProperties: true description: UTMs capturados no checkout (utm_source, utm_medium, …). salesRep: type: object nullable: true description: >- Quem vendeu, quando resolvido. `null` em venda direta, código que não resolveu ou vendedor com cadastro removido. Um vendedor desativado continua aparecendo aqui — desligar não muda a atribuição já gravada. properties: id: type: string name: type: string refCode: type: string salesRefCode: type: string nullable: true description: >- Código de referência bruto gravado no pagamento, mesmo quando `salesRep` é null (typo, código de outra loja, vendedor removido). createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object properties: error: type: object required: - type - message properties: type: type: string description: >- `authentication` (401), `insufficient_scope` (403), `invalid_request` (400) ou `not_found` (404). message: type: string param: type: string description: Parâmetro que falhou, em `invalid_request`. requiredScope: type: string description: Escopo que falta, em `insufficient_scope`. responses: Error: description: Erro content: application/json: schema: $ref: '#/components/schemas/Error' InsufficientScope: description: A chave é válida, mas não tem o escopo exigido pela operação. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: type: insufficient_scope message: Esta chave de API não tem o escopo students:read. requiredScope: students:read securitySchemes: bearerAuth: type: http scheme: bearer ````