> ## 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 virtual account deposits

> List the deposits received by a single virtual account, newest first. The virtual account must belong to you.

The response is a **bare JSON array** of deposit objects — there is no envelope and no pagination metadata. Page through results with `limit`/`offset` and infer "more pages" from whether a full page was returned.

**Query parameters**

-   `limit` — page size, clamped to `1`–`100` (out-of-range values are clamped, never rejected); defaults to `10`.
-   `offset` — number of deposits to skip, clamped to `0` or greater; defaults to `0`.

Each deposit carries `status` (`PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`, `KYT_PENDING`, `KYT_REJECTED`), the `amount`/`currency`, a `fees` breakdown with `net_amount`/`net_currency`, and counterparty info. Prefer the unified `source` object (it carries rail-specific tracking ids such as `imad`/`omad` for wires and `trace_number` for ACH) over the legacy `sender`. All money values are decimal strings.

**Example response (200):**

```json
[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "virtual_account_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "amount": "1000.00",
    "currency": "USD",
    "status": "COMPLETED",
    "sender": {
      "name": "Acme Corp",
      "account_number": "****7890",
      "address": "123 Market St, San Francisco, CA"
    },
    "recipient": {
      "name": "Jane Doe",
      "company_name": "Doe Holdings LLC",
      "country": "US"
    },
    "payment_rail": "WIRE",
    "settlement_tx_hash": null,
    "source": {
      "name": "Acme Corp",
      "account_number": "****7890",
      "address": "123 Market St, San Francisco, CA",
      "payment_rail": "WIRE",
      "reference_number": null,
      "imad": "20260625MMQFMP3K000123",
      "omad": "20260625L1B7HU5R000456",
      "trace_number": null
    },
    "fees": {
      "base_fees": {
        "fixed_fee": "1.50",
        "percentage_fee": "2.00",
        "fx_markup": "0"
      },
      "client_markup": {
        "fixed_fee": "0.00",
        "percentage_fee": "1.00",
        "fx_markup": "0"
      },
      "total_fees": "4.50"
    },
    "net_amount": "995.50",
    "net_currency": "USD",
    "created_at": "2026-06-20T14:32:00.000Z",
    "updated_at": "2026-06-20T14:35:10.000Z",
    "metadata": {
      "invoice_id": "INV-2026-0042"
    }
  }
]
```

{/* 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/virtual-accounts/{virtual_account_id}/deposits
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/virtual-accounts/{virtual_account_id}/deposits:
    get:
      tags:
        - Virtual Accounts
      summary: List virtual account deposits
      description: >-
        List the deposits received by a single virtual account, newest first.
        The virtual account must belong to you.


        The response is a **bare JSON array** of deposit objects — there is no
        envelope and no pagination metadata. Page through results with
        `limit`/`offset` and infer "more pages" from whether a full page was
        returned.


        **Query parameters**


        -   `limit` — page size, clamped to `1`–`100` (out-of-range values are
        clamped, never rejected); defaults to `10`.

        -   `offset` — number of deposits to skip, clamped to `0` or greater;
        defaults to `0`.


        Each deposit carries `status` (`PENDING`, `COMPLETED`, `FAILED`,
        `REFUNDED`, `KYT_PENDING`, `KYT_REJECTED`), the `amount`/`currency`, a
        `fees` breakdown with `net_amount`/`net_currency`, and counterparty
        info. Prefer the unified `source` object (it carries rail-specific
        tracking ids such as `imad`/`omad` for wires and `trace_number` for ACH)
        over the legacy `sender`. All money values are decimal strings.


        **Example response (200):**


        ```json

        [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "virtual_account_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
            "amount": "1000.00",
            "currency": "USD",
            "status": "COMPLETED",
            "sender": {
              "name": "Acme Corp",
              "account_number": "****7890",
              "address": "123 Market St, San Francisco, CA"
            },
            "recipient": {
              "name": "Jane Doe",
              "company_name": "Doe Holdings LLC",
              "country": "US"
            },
            "payment_rail": "WIRE",
            "settlement_tx_hash": null,
            "source": {
              "name": "Acme Corp",
              "account_number": "****7890",
              "address": "123 Market St, San Francisco, CA",
              "payment_rail": "WIRE",
              "reference_number": null,
              "imad": "20260625MMQFMP3K000123",
              "omad": "20260625L1B7HU5R000456",
              "trace_number": null
            },
            "fees": {
              "base_fees": {
                "fixed_fee": "1.50",
                "percentage_fee": "2.00",
                "fx_markup": "0"
              },
              "client_markup": {
                "fixed_fee": "0.00",
                "percentage_fee": "1.00",
                "fx_markup": "0"
              },
              "total_fees": "4.50"
            },
            "net_amount": "995.50",
            "net_currency": "USD",
            "created_at": "2026-06-20T14:32:00.000Z",
            "updated_at": "2026-06-20T14:35:10.000Z",
            "metadata": {
              "invoice_id": "INV-2026-0042"
            }
          }
        ]

        ```
      operationId: get_v1-virtual-accounts-virtual-account-id-deposits
      parameters:
        - in: path
          name: virtual_account_id
          required: true
          schema:
            type: string
            format: uuid
          description: Virtual account UUID.
        - 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: limit
          required: false
          description: >-
            Page size. Out-of-range values are clamped to 1-100 (never
            rejected); defaults to 10.
          schema:
            type: integer
            default: 10
        - in: query
          name: offset
          required: false
          description: >-
            Number of deposits to skip. Negative values are clamped to 0;
            defaults to 0.
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                type: array
                description: Bare array of deposits — no envelope, no pagination metadata.
                items:
                  $ref: '#/components/schemas/Deposit'
        '400':
          description: >-
            Malformed id — `virtual_account_id` is not a valid UUID. Ids are
            format-validated **before** lookup, so a syntactically invalid id
            returns `400` (not `404`); `404` is reserved for well-formed ids
            that do not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
              example:
                error: Invalid request data
                details:
                  - path: id
                    message: Invalid virtual account ID format
                    code: invalid_string
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
          apiKeyAuth: []
components:
  schemas:
    Deposit:
      type: object
      description: >-
        An inbound deposit received by a virtual account, as returned by the
        deposit read endpoints. Money values are decimal strings. Prefer the
        unified `source` object (it carries rail-specific tracking ids such as
        `imad`/`omad` for wires and `trace_number` for ACH) over the legacy
        `sender`.
      properties:
        id:
          type: string
          format: uuid
          description: Deposit UUID.
        virtual_account_id:
          type: string
          format: uuid
          description: UUID of the virtual account that received this deposit.
        amount:
          type: string
          description: Gross deposit amount (decimal string).
        currency:
          type: string
          description: Deposit currency.
        status:
          type: string
          enum:
            - PENDING
            - COMPLETED
            - FAILED
            - REFUNDED
            - KYT_PENDING
            - KYT_REJECTED
          description: Deposit status (UPPERCASE).
        sender:
          type:
            - object
            - 'null'
          description: >-
            Legacy counterparty shape (name, account_number, address only).
            Prefer `source`.
          properties:
            name:
              type:
                - string
                - 'null'
            account_number:
              type:
                - string
                - 'null'
            address:
              type:
                - string
                - 'null'
        recipient:
          type:
            - object
            - 'null'
          description: Recipient (the VA owner) summary.
          properties:
            name:
              type:
                - string
                - 'null'
            company_name:
              type:
                - string
                - 'null'
            country:
              type:
                - string
                - 'null'
        payment_rail:
          type:
            - string
            - 'null'
          description: Legacy top-level rail; mirrored on `source.payment_rail`.
        settlement_tx_hash:
          type:
            - string
            - 'null'
          description: On-chain settlement transaction hash, when applicable.
        source:
          type:
            - object
            - 'null'
          description: >-
            Unified counterparty / wire-tracking shape. Rail-specific
            identifiers are present only when relevant: ACT wires populate
            `reference_number`; Fedwire wires populate `imad`/`omad`; ACH
            populates `trace_number`.
          properties:
            name:
              type:
                - string
                - 'null'
            account_number:
              type:
                - string
                - 'null'
            address:
              type:
                - string
                - 'null'
            payment_rail:
              type:
                - string
                - 'null'
              description: >-
                The rail the deposit arrived on. `"wire"` on every wire-rail
                deposit observed in sandbox; `null` when not yet resolved.
            reference_number:
              type:
                - string
                - 'null'
            imad:
              type:
                - string
                - 'null'
              description: >-
                IMAD (Input Message Accountability Data): the Fedwire
                inbound-wire tracking identifier. Format varies by originating
                bank and differs between sandbox and production, so do not rely
                on a fixed shape or length. `null` on non-wire deposits.
            omad:
              type:
                - string
                - 'null'
              description: >-
                OMAD (Output Message Accountability Data): the Fedwire
                outbound-wire tracking identifier. Format varies by originating
                bank and differs between sandbox and production, so do not rely
                on a fixed shape or length. `null` on non-wire deposits.
            trace_number:
              type:
                - string
                - 'null'
        fees:
          $ref: '#/components/schemas/DepositFees'
        net_amount:
          type: string
          description: Amount after fees (decimal string).
        net_currency:
          type: string
          description: Currency of `net_amount` (3-letter ISO code).
        created_at:
          type: string
          description: ISO 8601 timestamp.
        updated_at:
          type: string
          description: ISO 8601 timestamp.
        metadata:
          type: object
          description: >-
            Customer-attached metadata, snapshotted from the parent VA at
            deposit creation.
          additionalProperties: true
      required:
        - id
        - virtual_account_id
        - amount
        - currency
        - status
        - created_at
        - updated_at
    ValidationErrorResponse:
      type: object
      description: >-
        Validation / request error. The body shape is **not uniform** across the
        API — it varies by endpoint and by which validation layer rejects the
        request. The fields below are the union of what may appear; treat them
        all as optional. Observed shapes include `{ code, message }`, `{ code,
        message, errors[] }`, `{ code, error, details[] }`, `{ error, details[]
        }`, and a nested `{ error: { code, message, details } }`. Always branch
        on the HTTP status, not on a fixed body shape.
      properties:
        code:
          type: string
        message:
          type: string
        error:
          type:
            - string
            - object
          description: >-
            A short error label (e.g. `"Invalid data"`), or on some endpoints a
            nested `{ code, message, details }` object.
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
            required:
              - field
              - message
        details:
          type:
            - array
            - object
          description: >-
            Per-issue detail. Shape varies by endpoint — typically an array of
            `{ message }` or `{ path, message, code }`, occasionally an object.
    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
    DepositFees:
      type: object
      description: >-
        Deposit fee breakdown. `total_fees` equals the per-component sum of
        `base_fees` + `client_markup`.
      properties:
        base_fees:
          $ref: '#/components/schemas/DepositFeeBreakdown'
        client_markup:
          $ref: '#/components/schemas/DepositFeeBreakdown'
        total_fees:
          type: string
          description: Sum of all fee components (decimal string).
      required:
        - base_fees
        - client_markup
        - total_fees
    DepositFeeBreakdown:
      type: object
      description: >-
        One leaf of the deposit fee breakdown. All values are decimal strings;
        `fx_markup` may be negative.
      properties:
        fixed_fee:
          type: string
          description: Fixed fee component (decimal string, >= 0).
        percentage_fee:
          type: string
          description: Percentage fee component as a dollar amount (decimal string, >= 0).
        fx_markup:
          type: string
          description: >-
            FX markup component as a dollar amount (decimal string; may be
            negative).
      required:
        - fixed_fee
        - percentage_fee
        - fx_markup
  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`.

````