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

# Fetch Agent Institution Wallet Ledger

> Use this API to fetch a paginated list of wallet ledger entries for a given Agent Institution.
Includes credits (recharges) and debits (bill payments).
Results can be filtered by date range, transaction type, or UTR.
All request body fields are optional. An empty body returns all entries.

<Note>
The ledger lists wallet credits (recharges) and debits (bill payments). On the prefunding model, each bill payment also produces freeze and unfreeze hold entries against the prefunded balance. On the shortfall (postfunding) model, debits can take the running balance negative, reflecting the amount drawn against the credit line.
</Note>



## OpenAPI

````yaml openapi/bbps/bbps-cou.yaml post /bbps/cou/agent/{agentId}/wallet/ledger
openapi: 3.0.3
info:
  title: BBPS for Customers (Customer Operating Unit)
  version: 1.0.0
  description: >
    APIs for Agent Institutions to integrate with the Bharat Bill Payment System
    (BBPS) as a Customer Operating Unit (COU). These APIs enable bill discovery,
    bill fetch, bill payment, ticket management, and wallet operations.
servers:
  - url: https://sandbox.cashfree.com
    description: Sandbox (Testing) environment.
  - url: https://api.cashfree.com
    description: Production environment.
security:
  - XClientID: []
    XClientSecret: []
paths:
  /bbps/cou/agent/{agentId}/wallet/ledger:
    post:
      tags:
        - Wallet
      summary: Fetch Agent Institution Wallet Ledger
      description: >-
        Use this API to fetch a paginated list of wallet ledger entries for a
        given Agent Institution.

        Includes credits (recharges) and debits (bill payments).

        Results can be filtered by date range, transaction type, or UTR.

        All request body fields are optional. An empty body returns all entries.


        <Note>

        The ledger lists wallet credits (recharges) and debits (bill payments).
        On the prefunding model, each bill payment also produces freeze and
        unfreeze hold entries against the prefunded balance. On the shortfall
        (postfunding) model, debits can take the running balance negative,
        reflecting the amount drawn against the credit line.

        </Note>
      operationId: fetchAgentWalletLedger
      parameters:
        - name: agentId
          in: path
          required: true
          description: >-
            The Agent Institution ID (bbpsAgentInstituteId) that owns the
            wallet. This is the parent institution identifier, not the
            channel-specific agent_id used in the Bill Fetch and Bill Payment
            APIs.
          schema:
            type: string
          example: AI15
        - name: page
          in: query
          required: false
          description: Zero-indexed page number. Default is 0.
          schema:
            type: integer
            default: 0
          example: 0
        - name: size
          in: query
          required: false
          description: Number of entries per page. Default is 20.
          schema:
            type: integer
            default: 20
          example: 20
        - $ref: '#/components/parameters/apiVersionHeader'
      requestBody:
        description: Request parameters to filter wallet ledger entries.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                start_date_time:
                  type: string
                  description: >-
                    Filter entries from this datetime. Format: yyyy-MM-dd
                    HH:mm:ss.
                  example: '2025-01-01 00:00:00'
                end_date_time:
                  type: string
                  description: >-
                    Filter entries up to this datetime. Format: yyyy-MM-dd
                    HH:mm:ss.
                  example: '2025-01-31 23:59:59'
                sale_type:
                  type: string
                  description: Filter by transaction type.
                  enum:
                    - CREDIT
                    - DEBIT
                  example: DEBIT
                utr:
                  type: string
                  description: Filter by Unique Transaction Reference number.
                  example: UTR123456789
            example:
              start_date_time: '2025-01-01 00:00:00'
              end_date_time: '2025-01-31 23:59:59'
              sale_type: DEBIT
              utr: UTR123456789
      responses:
        '200':
          description: >-
            Success response for fetching a paginated list of wallet ledger
            entries for a given Agent Institution.
          headers:
            x-api-version:
              $ref: '#/components/headers/x-api-version'
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    description: List of ledger entries for the current page.
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          description: Unique ledger entry ID.
                          example: 1001
                        wallet_id:
                          type: integer
                          description: Internal wallet ID.
                          example: 42
                        event:
                          type: string
                          nullable: true
                          description: >-
                            Ledger event type for this entry. Bill payment
                            entries use BILL_PAYMENT_FREEZE (amount held when a
                            payment is initiated), BILL_PAYMENT_UNFREEZE (hold
                            released on completion, timeout, or failure), and
                            BILL_PAYMENT_DEBIT (actual debit on a successful
                            payment). Wallet top-ups use WALLET_SEED or a
                            recharge event.
                          example: BILL_PAYMENT_DEBIT
                        event_id:
                          type: string
                          nullable: true
                          description: >-
                            Identifier that links this entry to its source. For
                            bill payment events, this is the transaction_ref_id
                            returned by the Bill Payment API, so you can
                            correlate ledger entries with a specific payment.
                          example: CH0162455XTQK9MIPNYZ
                        sale_type:
                          type: string
                          description: >-
                            Direction of the transaction. CREDIT indicates a
                            wallet top-up; DEBIT indicates a bill payment.
                          enum:
                            - CREDIT
                            - DEBIT
                          example: DEBIT
                        amount:
                          type: number
                          description: Transaction amount in INR.
                          example: 250
                        closing_balance:
                          type: number
                          description: Wallet balance after this transaction in INR.
                          example: 4750
                        utr:
                          type: string
                          description: Unique Transaction Reference number.
                          example: UTR123456789
                        added_on:
                          type: string
                          description: 'Entry creation datetime. Format: yyyy-MM-dd HH:mm:ss'
                          example: '2025-01-15 10:30:00'
                        updated_on:
                          type: string
                          description: >-
                            Entry last updated datetime. Format: yyyy-MM-dd
                            HH:mm:ss
                          example: '2025-01-15 10:30:05'
                  size:
                    type: integer
                    description: Number of entries per page.
                    example: 20
                  page:
                    type: integer
                    description: Current page number (zero-indexed).
                    example: 0
                  last:
                    type: boolean
                    description: Indicates whether this is the last page.
                    example: true
              example:
                content:
                  - id: 1001
                    wallet_id: 42
                    event: BILL_PAYMENT_DEBIT
                    event_id: CH0162455XTQK9MIPNYZ
                    sale_type: DEBIT
                    amount: 250
                    closing_balance: 4750
                    utr: UTR123456789
                    added_on: '2025-01-15 10:30:00'
                    updated_on: '2025-01-15 10:30:05'
                size: 20
                page: 0
                last: true
        '400':
          description: Bad request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '429':
          description: Rate Limit Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
components:
  parameters:
    apiVersionHeader:
      in: header
      name: x-api-version
      required: true
      description: API version to be used. Format is YYYY-MM-DD.
      schema:
        type: string
        default: '2025-01-01'
      example: '2025-01-01'
      x-ignore: true
  headers:
    x-api-version:
      schema:
        type: string
        format: YYYY-MM-DD
        enum:
          - '2025-01-01'
      description: >-
        The API version used to process the request. The current version is
        `2025-01-01`.
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the validation or request error.
          example: >-
            bill_fetch_request.agent_id : is missing in the request. Value
            received: 
        code:
          type: string
          description: >-
            Machine-readable error code identifying the specific validation
            failure.
          example: bill_fetch_request.agent_id_missing
        type:
          type: string
          description: Category of the error, indicating the error class.
          example: invalid_request_error
    UnauthorizedResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the authentication failure.
          example: authentication Failed
        code:
          type: string
          description: Machine-readable error code identifying the failure reason.
          example: request_failed
        type:
          type: string
          description: Category of the error, indicating the error class.
          example: authentication_error
    RateLimitResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the rate limit breach.
          example: Too many requests from IP. Check headers
        code:
          type: string
          description: Machine-readable error code identifying the failure reason.
          example: request_failed
        type:
          type: string
          description: Category of the error, indicating the error class.
          example: rate_limit_error
    InternalServerErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Human-readable description of the server-side error.
          example: internal Server Error
        code:
          type: string
          description: Machine-readable error code identifying the failure reason.
          example: internal_error
        type:
          type: string
          description: Category of the error, indicating the error class.
          example: api_error
  securitySchemes:
    XClientID:
      type: apiKey
      in: header
      name: x-client-id
      description: >-
        Your unique client identifier issued by Cashfree. You can find this in
        your [Merchant
        Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).
    XClientSecret:
      type: apiKey
      in: header
      name: x-client-secret
      description: >-
        Your unique client secret issued by Cashfree. Keep this confidential and
        never expose it in client-side code. You can find this in your [Merchant
        Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).

````