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

# List a league's payout ledger (read-only)

> Newest first. There is no v1 endpoint to create or settle payments — payments are produced by in-app organizer actions.



## OpenAPI

````yaml /api-reference/openapi.json get /leagues/{leagueId}/payments
openapi: 3.1.0
info:
  title: Whistle Partner API
  version: 1.0.0
  summary: >-
    Server-to-server REST API for Whistle — post games, manage officials, track
    payouts.
  description: >-
    Whistle's v1 partner API lets league management systems and partner
    automations create leagues and games, add and assign sports officials, read
    the payout ledger, and receive webhooks. All requests require a partner API
    key (`Authorization: Bearer whk_…`). Responses use a consistent envelope:
    success is `{"data": …}`, failure is `{"error": "<code>"}`.


    **Scoping:** partner keys are bound to a `source` namespace. A key reads and
    mutates only leagues whose `source` matches (plus leagues explicitly granted
    to it), and webhook endpoints it registered. Out-of-scope resources answer
    `404` identically to nonexistent ones — "not yours" and "not there" are
    deliberately indistinguishable. Write `source` is derived from the key: omit
    the field or echo your own value; any other value returns `400
    source_mismatch`.


    **Contract stability:** v1 response field shapes, status strings, and
    webhook event names are additive-only. Breaking changes ship as `/api/v2` —
    v1 is never mutated in place.


    **Idempotency:** `source` + `externalId` form the upsert key on leagues,
    games, and officials. Re-posting the same `(source, externalId)` updates
    instead of duplicating. Re-using a game `externalId` under a different
    league returns `409 external_id_conflict`.


    **Money:** requests take dollars (`payDollars`); responses return both
    integer cents (`payCents`, `amountCents`) and dollars. **Time:** all
    timestamps are ISO 8601 UTC (`2026-07-09T18:00:00.000Z`).


    List endpoints are not paginated and take no filter parameters (except
    `?limit=` on webhook deliveries). The API has no CORS support — it is
    server-to-server only.
  contact:
    name: HuddleUp Sports support
    email: tommy@huddleup-sports.com
    url: https://huddleup-sports.com/docs/developers
servers:
  - url: https://whistle.huddleup-sports.com/api/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Index
    description: Self-describing API index
  - name: Leagues
    description: Create, read, and update leagues
  - name: Games
    description: Batch-import games, read, update, cancel
  - name: Officials
    description: Add, approve, list, and remove officials; assign them to games
  - name: Assignments
    description: Who is covering which game
  - name: Payments
    description: Read-only payout ledger
  - name: Webhooks
    description: Register endpoints and inspect deliveries
paths:
  /leagues/{leagueId}/payments:
    parameters:
      - $ref: '#/components/parameters/leagueId'
    get:
      tags:
        - Payments
      summary: List a league's payout ledger (read-only)
      description: >-
        Newest first. There is no v1 endpoint to create or settle payments —
        payments are produced by in-app organizer actions.
      operationId: listPayments
      responses:
        '200':
          description: Array of payments
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Payment'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    leagueId:
      name: leagueId
      in: path
      required: true
      schema:
        type: string
      description: Whistle league id (`id` from league responses).
  schemas:
    Payment:
      type: object
      properties:
        id:
          type: string
        positionId:
          type: string
        officialId:
          type: string
        amountCents:
          type: integer
        amountDollars:
          type: number
        currency:
          type: string
        mode:
          type: string
          enum:
            - platform
            - offline
        status:
          type: string
          enum:
            - pending
            - processing
            - paid
            - requires_card
            - failed
          description: >-
            pending = created, not yet charged (offline stays here until
            organizer marks paid); processing = platform charge created,
            awaiting settlement; paid = settled; requires_card / failed =
            recoverable platform failures.
        paidAt:
          type:
            - string
            - 'null'
          format: date-time
        failureCode:
          type:
            - string
            - 'null'
        failureMessage:
          type:
            - string
            - 'null'
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - positionId
        - officialId
        - amountCents
        - amountDollars
        - currency
        - mode
        - status
        - paidAt
        - failureCode
        - failureMessage
        - createdAt
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: >-
            snake_case error code. Two codes carry a parameter suffix:
            `invalid_startsAt:<value>` and `unknown_event:<name>`.
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: unauthorized
    NotFound:
      description: >-
        Resource not found **or outside your key's scope** — the two cases are
        deliberately indistinguishable (same status and code). Codes:
        `league_not_found`, `game_not_found`, `official_not_found`,
        `position_not_found`, `not_a_member`, `endpoint_not_found`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: league_not_found
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Partner API key: `Authorization: Bearer whk_…`. Keys are issued by the
        Whistle team (email tommy@huddleup-sports.com), shown once at issuance,
        and bound to your `source` namespace — they access only your leagues
        (plus explicit grants) and your webhook endpoints. Any auth failure
        returns `401 {"error":"unauthorized"}`; the API never returns 403 —
        out-of-scope resources answer 404 exactly like nonexistent ones.

````