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

# List payouts

> List the payouts belonging to your client, newest first by default. Supports filtering, search, pagination, and sorting.

**This endpoint rejects unknown query parameters** — sending a parameter not listed below (e.g. a camelCase typo like `?virtualAccountId`) returns `400` instead of silently ignoring it.

The response is an envelope (`{ payouts, total, page, limit, total_pages }`), not a top-level array.

{/* version-stamp:start — generated by scripts/stamp-versions.ts, do not edit */}

<Info>Stable since **2025-01-01** — unchanged in **2026-04-14**.</Info>

{/* version-stamp:end */}


## OpenAPI

````yaml /openapi/kira-api.2026-04-14.json get /v1/payouts
openapi: 3.1.0
info:
  title: Kira API
  version: '2026-04-14'
  description: >-
    REST API for users, KYC/KYB verification, virtual accounts, payouts,
    recipients, and webhooks. Every request requires an `x-api-key` header and a
    bearer access token (see Authentication). Pin your account to version
    `2026-04-14` before integrating.
  contact:
    name: Kira API Support
    email: support@kirafin.ai
servers:
  - url: https://api.balampay.com
    description: Production
  - url: https://api.balampay.com/sandbox
    description: Sandbox
security:
  - bearerAuth: []
    apiKeyAuth: []
tags:
  - name: Authentication
  - name: Versioning
  - name: Users
  - name: Virtual Accounts
  - name: Quotations
  - name: Payouts
  - name: Recipients
  - name: Reference
paths:
  /v1/payouts:
    get:
      tags:
        - Payouts
      summary: List payouts
      description: >-
        List the payouts belonging to your client, newest first by default.
        Supports filtering, search, pagination, and sorting.


        **This endpoint rejects unknown query parameters** — sending a parameter
        not listed below (e.g. a camelCase typo like `?virtualAccountId`)
        returns `400` instead of silently ignoring it.


        The response is an envelope (`{ payouts, total, page, limit, total_pages
        }`), not a top-level array.
      operationId: get_v1-payouts
      parameters:
        - in: header
          name: X-Api-Version
          required: false
          description: >-
            Optional. The date-versioned API version to apply for this request
            (e.g. `2026-04-14`). When sent it always wins, even over your pinned
            account default. When omitted, the API uses your account's pinned
            version if set, otherwise a baseline default.
          schema:
            type: string
            example: '2026-04-14'
        - in: query
          name: user_id
          required: false
          description: Filter by user UUID.
          schema:
            type: string
            format: uuid
        - in: query
          name: status
          required: false
          description: Filter by client-facing payout status.
          schema:
            type: string
            enum:
              - CREATED
              - PENDING
              - PROCESSING
              - COMPLETED
              - FAILED
              - CANCELLED
              - IN_REVIEW
              - KYT_PENDING
        - in: query
          name: recipient_id
          required: false
          description: Filter by recipient UUID.
          schema:
            type: string
            format: uuid
        - in: query
          name: virtual_account_id
          required: false
          description: Filter by originating virtual account UUID.
          schema:
            type: string
            format: uuid
        - in: query
          name: origin
          required: false
          description: Filter by payout origin.
          schema:
            type: string
            enum:
              - deposit
              - payout
              - api
        - in: query
          name: from_date
          required: false
          description: >-
            Inclusive lower bound on the created timestamp. ISO 8601 date-time
            or a date-only `YYYY-MM-DD` string.
          schema:
            type: string
        - in: query
          name: to_date
          required: false
          description: >-
            Inclusive upper bound on the created timestamp. ISO 8601 date-time
            or a date-only `YYYY-MM-DD` string.
          schema:
            type: string
        - in: query
          name: search
          required: false
          description: Free-text search (max 255 characters).
          schema:
            type: string
            maxLength: 255
        - in: query
          name: page
          required: false
          description: 1-indexed page number.
          schema:
            type: integer
            minimum: 1
            default: 1
        - in: query
          name: limit
          required: false
          description: Page size (1-100).
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - in: query
          name: sort_by
          required: false
          description: Field to sort by.
          schema:
            type: string
            enum:
              - created_at
              - from_amount
              - status
            default: created_at
        - in: query
          name: sort_order
          required: false
          description: Sort direction.
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
        - in: query
          name: metadata
          required: false
          description: >-
            Stripe-style metadata filter — `?metadata[key]=value` deep-object
            form. Each key must be 1-40 characters and must not contain `[` or
            `]`. Multiple keys are AND-ed.
          style: deepObject
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: object
                description: Paginated list envelope (not a top-level array).
                properties:
                  payouts:
                    type: array
                    items:
                      $ref: '#/components/schemas/PayoutListItem'
                  total:
                    type: integer
                    description: Total payouts matching the filters.
                  page:
                    type: integer
                  limit:
                    type: integer
                  total_pages:
                    type: integer
                required:
                  - payouts
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
          apiKeyAuth: []
components:
  schemas:
    PayoutListItem:
      type: object
      description: A single payout in the `GET /v1/payouts` list envelope.
      properties:
        payout_id:
          type: string
          format: uuid
        short_id:
          type: string
          description: Human-friendly short identifier.
        user_id:
          type: string
          format: uuid
        virtual_account_id:
          type:
            - string
            - 'null'
          format: uuid
          description: Null for payouts not tied to a virtual account.
        created_at:
          type: string
          description: ISO 8601 timestamp.
        status:
          type: string
          description: >-
            Client-facing payout status (UPPERCASE): CREATED, KYT_PENDING,
            PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED, IN_REVIEW. See
            the state-machines guide.
        origin:
          type: string
          enum:
            - api
            - payout
            - deposit
          description: >-
            Same enum and meaning as `PayoutDetailResponse.origin` (`deposit` |
            `payout` | `api`) — confirmed via the same `?origin=` filter
            validation.
        from_amount:
          type: string
          description: >-
            Decimal string. Amount on the source/funding side — matches
            `PayoutDetailResponse.from_amount` for the same payout.
        from_currency:
          type: string
          description: >-
            Same meaning as `PayoutDetailResponse.from_currency` — the
            source/funding-side currency (`"USDC"` on a crypto-funded payout,
            not always USD).
        to_amount:
          type: string
          description: >-
            Decimal string. Amount on the destination side — matches
            `PayoutDetailResponse.to_amount` for the same payout.
        to_currency:
          type:
            - string
            - 'null'
          description: >-
            Same meaning as `PayoutDetailResponse.to_currency` — the
            destination/recipient currency, `null` until resolved.
        payment_method:
          type:
            - string
            - 'null'
          description: 'Lowercased recipient rail: wire, wallet, ach.'
        sender_name:
          type:
            - string
            - 'null'
        recipient_name:
          type:
            - string
            - 'null'
        reference:
          type:
            - string
            - 'null'
        memo:
          type:
            - string
            - 'null'
        metadata:
          type: object
          additionalProperties: true
      required:
        - payout_id
        - user_id
        - created_at
        - status
        - origin
        - from_amount
        - from_currency
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
        code:
          type: string
        statusCode:
          type: number
        error:
          type: string
        timestamp:
          type: string
        path:
          type: string
        details: {}
      required:
        - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token from `POST /auth` (the `data.access_token` value).
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key issued by Kira. Required on every request, including `/auth`.

````