> ## 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.

# Mint a download URL for a completed report

> Minted on access — there is no "generate link" button. One authenticated,
ownership-checked call returns a fresh v4 signed URL (TTL 300s) as
`{ url, expires_at }`. The signed URL itself is unauthenticated — that is
what a signed URL is — but it is only issued to a caller the platform has
already identified, and every issuance is logged. The URL is never stored
on the row; each call mints a new one.




## OpenAPI

````yaml /openapi/payment-acceptance.json get /payments/reports/{report_id}/download
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/{report_id}/download:
    get:
      tags:
        - Server-to-Server Payments
      summary: Mint a download URL for a completed report
      description: >
        Minted on access — there is no "generate link" button. One
        authenticated,

        ownership-checked call returns a fresh v4 signed URL (TTL 300s) as

        `{ url, expires_at }`. The signed URL itself is unauthenticated — that
        is

        what a signed URL is — but it is only issued to a caller the platform
        has

        already identified, and every issuance is logged. The URL is never
        stored

        on the row; each call mints a new one.
      operationId: lite.server-to-server.downloadPaymentReport
      parameters:
        - $ref: '#/components/parameters/report_id'
        - $ref: '#/components/parameters/x-correlation-id'
      responses:
        '200':
          $ref: '#/components/responses/ReportDownloadResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    report_id:
      name: report_id
      in: path
      required: true
      description: Unique identifier of the report (UUID v4)
      schema:
        type: string
        format: uuid
        example: 3f1c0b2a-0e5d-4a1b-9c2f-6a7b8c9d0e1f
    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:
    ReportDownloadResponse:
      description: A fresh signed download URL
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ReportDownload'
    BadRequest:
      description: >
        The request was invalid or malformed.


        Returned when:

        - Request validation fails (missing required fields, invalid field
        formats)

        - Payment details do not match the session (amount, currency, order
        reference mismatch)

        - The operation is not allowed given the current resource state
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    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'
    NotFound:
      description: |
        The requested resource was not found.

        Returned when:
        - The specified resource ID does not exist
        - The path does not match any known endpoint
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ReportDownload:
      type: object
      required:
        - url
        - expires_at
      properties:
        url:
          type: string
          format: uri
          description: Short-lived signed download URL. Open directly; do not persist.
          example: >-
            https://storage.googleapis.com/reports-bucket/reports/mer_1/exp_1.csv?X-Goog-Signature=...
        expires_at:
          type: string
          format: date-time
          description: >-
            Instant the signed URL stops working. Call this endpoint again for a
            fresh one.
          example: '2026-09-06T12:08:11.000Z'
    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'
  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 <token>.

````