> ## Documentation Index > Fetch the complete documentation index at: https://docs.lite.sa/llms.txt > Use this file to discover all available pages before exploring further. # List payment reports > The merchant's own reports, newest first, in the same pagination envelope as GET /payments. DELETED rows are never returned; a COMPLETED report whose retention window has passed reports as EXPIRED. No signed URL is included — call GET /payments/reports/{report_id}/download to mint one. ## OpenAPI ````yaml /openapi/payment-acceptance.json get /payments/reports openapi: 3.1.0 info: title: lite - Payment Acceptance version: 1.0.0 servers: - url: https://api.lite.sa description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: 3DS Authentication description: Standalone payer authentication via the 3DS standard - name: Hosted Checkout description: Create, manage and deploy hosted checkout pages - name: Payment Links description: Create, manage and audit shareable payment links - name: Server-to-Server Payments description: Direct payment API for server-side integrations paths: /payments/reports: get: tags: - Server-to-Server Payments summary: List payment reports description: > The merchant's own reports, newest first, in the same pagination envelope as GET /payments. DELETED rows are never returned; a COMPLETED report whose retention window has passed reports as EXPIRED. No signed URL is included — call GET /payments/reports/{report_id}/download to mint one. operationId: lite.server-to-server.listPaymentReports parameters: - $ref: '#/components/parameters/x-correlation-id' - name: page in: query required: false schema: type: integer minimum: 1 default: 1 description: Page number - name: page_size in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Number of items per page - name: status in: query required: false schema: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED description: >- Filter by the stored status. EXPIRED is derived at read time and is not a valid filter value. responses: '200': $ref: '#/components/responses/ReportListResponse' '401': $ref: '#/components/responses/Unauthorized' components: parameters: x-correlation-id: name: x-correlation-id in: header required: false description: >- Unique identifier for request tracing. Generated by the client or server if not provided. schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 responses: ReportListResponse: description: A page of reports content: application/json: schema: $ref: '#/components/schemas/ReportListResponse' Unauthorized: description: | Authentication failed — missing or invalid token. Returned when: - The JWT bearer token is missing, expired, or has an invalid signature - The API key is missing or invalid - The authenticated session token is invalid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: ReportListResponse: type: object required: - data - pagination_data properties: data: type: array description: Reports for the requested page, newest first items: $ref: '#/components/schemas/ReportDetail' pagination_data: type: object required: - count - pages - page - page_size - has_next - has_previous properties: count: type: integer description: Total number of items example: 42 pages: type: integer description: Total number of pages example: 3 page: type: integer description: Current page number example: 1 page_size: type: integer description: Items per page example: 20 has_next: type: boolean description: Whether there is a next page example: true has_previous: type: boolean description: Whether there is a previous page example: false ErrorResponse: type: object required: - error properties: error: type: object required: - code - message - timestamp properties: code: type: string description: Error code identifying the type of error example: PAYMENT_DETAILS_MISMATCH message: type: string description: Human-readable error description example: The request was invalid or malformed details: type: object description: Additional error details correlationId: type: string format: uuid description: Correlation ID for tracking the request example: 550e8400-e29b-41d4-a716-446655440000 timestamp: type: string format: date-time description: Timestamp when the error occurred example: '2024-12-16T10:30:00.000Z' ReportDetail: type: object required: - id - status - format - filters - created_at properties: id: type: string format: uuid description: Report identifier example: 3f1c0b2a-0e5d-4a1b-9c2f-6a7b8c9d0e1f status: type: string enum: - QUEUED - RUNNING - COMPLETED - FAILED - EXPIRED description: >- Derived status. A COMPLETED report whose retention window (expires_at) has passed reports as EXPIRED. example: COMPLETED format: type: string enum: - CSV - XLSX example: CSV filters: allOf: - $ref: '#/components/schemas/ReportFilters' - type: object required: - to_date description: >- The materialized filter set used for this report. The upper date bound is always concrete. row_count: type: integer description: Exact row count. Present once the report is COMPLETED. example: 1284 created_at: type: string format: date-time example: '2026-09-06T12:00:00.000Z' completed_at: type: string format: date-time example: '2026-09-06T12:03:11.000Z' expires_at: type: string format: date-time description: >- Informational retention boundary. Past this instant the report is EXPIRED. example: '2026-12-05T12:03:11.000Z' error_code: type: string description: >- Stable failure code the caller can branch on. Present only when status is FAILED. example: MAX_ROWS_EXCEEDED error_message: type: string description: Caller-safe failure message. Present only when status is FAILED. example: >- This report matched too many payments. Narrow your filters and try again. ReportFilters: type: object description: >- Same filter set accepted by GET /payments. Omit entirely to include every payment for the merchant in the report (still bounded by the frozen upper date and the row ceiling). properties: status: type: array items: type: string enum: - CREATED - PENDING - AUTHORIZED - FAILED - EXPIRED - AUTHORIZATION_REVERSED - VOIDED - PARTIALLY_CAPTURED - CAPTURED - REFUNDED - DISPUTED - DISPUTE_CHALLENGED - ARBITRATION_INITIATED - ARBITRATION_LOST - CHARGEDBACK - REQUIRES_ACTION description: Filter by payment status payment_method: type: array items: type: string enum: - CARD - APPLE_PAY - GOOGLE_PAY - SAMSUNG_PAY - MDES - SCOF - VTS - VCOF - IBAN description: Filter by payment method card_brand: type: array items: type: string enum: - MADA - VISA - MASTERCARD - DISCOVER - JCB - UPI - AMEX - GCCNET - MAESTRO - UNKNOWN description: Filter by card brand channel_type: type: string description: Filter by channel type channel_id: type: string description: Filter by channel id from_date: type: string format: date-time description: Start date filter (ISO 8601) to_date: type: string format: date-time description: >- End date filter (ISO 8601). On the create-report request this is frozen to the request time when omitted, so an identical request replayed later still dedupes to the same row set. amount_min: type: integer minimum: 0 description: Minimum amount, minor units amount_max: type: integer minimum: 0 description: Maximum amount, minor units customer_id: type: string description: Filter by customer id decline_reason: type: string description: Filter by decline reason last_four: type: string pattern: ^\d{4}$ description: Filter by the last 4 digits of the card rrn: type: string description: Filter by retrieval reference number approval_code: type: string description: Filter by approval code securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for service-to-service or merchant authentication. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token obtained from user authentication. Passed as Authorization: Bearer . ````