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

# Get Wallet Details

> Use this API to fetch wallet details and associated sub-wallet balances for a specified user. You can query by wallet ID, card ID, or a combination of either with a sub-wallet ID.


<AccordionGroup>
  <Accordion title="Request parameters">
    `user_id` is always required. You must also provide one of the following identifier combinations.

    | Combination              | Required parameters                        |
    | ------------------------ | ------------------------------------------ |
    | By wallet                | `user_id`, `wallet_id`                     |
    | By card                  | `user_id`, `card_id`                       |
    | By wallet and sub-wallet | `user_id`, `wallet_id`, `cf_sub_wallet_id` |
    | By card and sub-wallet   | `user_id`, `card_id`, `cf_sub_wallet_id`   |
  </Accordion>

  <Accordion title="Response behaviour">
    The response always includes wallet details and sub-wallet details. The following rules determine what additional data is returned based on the identifiers you provide.

    * If you provide `wallet_id` and the wallet has no associated card, the response returns wallet and sub-wallet details only.
    * If you provide `wallet_id` and the wallet has an associated card, the response also includes card details.
    * If you provide `card_id`, the response includes card details alongside wallet and sub-wallet details.
    * If you provide both `wallet_id` and `cf_sub_wallet_id`, the response returns details for the specified sub-wallet only.
    * If you provide both `card_id` and `cf_sub_wallet_id`, the response returns details for the specified sub-wallet along with wallet and card details.
  </Accordion>
</AccordionGroup>


## OpenAPI

````yaml /openapi/ppi/ppi.yaml post /ppi/wallet/details
openapi: 3.0.3
info:
  title: PPI Wallet API
  description: >-
    API for managing PPI (Prepaid Payment Instrument) wallets and sub-wallets,
    including credit and debit operations.
  version: 1.0.0
  contact:
    name: PPI Service Team
    email: support@cashfree.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: https://api.cashfree.com
    description: Production server.
  - url: https://sandbox.cashfree.com
    description: Sandbox server.
security:
  - XClientID: []
    XClientSecret: []
tags:
  - name: Wallet Management
    description: Operations related to PPI wallet management.
  - name: User Management
    description: Operations related to user management within the PPI system.
  - name: Beneficiary Management
    description: Operations related to beneficiary management for users.
  - name: KYC Management
    description: Operations related to KYC (Know Your Customer) management.
  - name: Transfers
    description: Operations related to transfer.
paths:
  /ppi/wallet/details:
    post:
      tags:
        - Wallet Management
      summary: Get Wallet Details
      description: >
        Use this API to fetch wallet details and associated sub-wallet balances
        for a specified user. You can query by wallet ID, card ID, or a
        combination of either with a sub-wallet ID.
      operationId: fetchWalletBalance
      parameters:
        - $ref: '#/components/parameters/global_x_api_version'
      requestBody:
        description: >-
          Request parameters to fetch wallet and sub-wallet details, including
          current balances, for a user.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FetchWalletBalanceRequest'
            examples:
              fetchByWallet:
                summary: Fetch by wallet ID
                value:
                  user_id: USER827364
                  wallet_id: WALLET936721
              fetchByCard:
                summary: Fetch by card ID
                value:
                  user_id: USER827364
                  card_id: CARDR827364
              fetchByWalletAndSubWallet:
                summary: Fetch by sub-wallet ID
                value:
                  user_id: USER827364
                  wallet_id: WALLET936721
                  cf_sub_wallet_id: '35246543210987654321'
              fetchByCardAndSubWallet:
                summary: Fetch by card ID and sub-wallet ID
                value:
                  user_id: USER827364
                  card_id: CARDR827364
                  cf_sub_wallet_id: '35246543210987654321'
      responses:
        '200':
          $ref: '#/components/responses/FetchWalletBalanceResponse'
        '400':
          description: Bad request - Invalid input parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponse'
              examples:
                user_id_missing:
                  summary: User ID missing
                  value:
                    code: user_id_missing
                    type: validation_error
                    message: user_id is missing in the request
                user_id_invalid:
                  summary: User ID value is invalid
                  value:
                    code: user_id_value_invalid
                    type: validation_error
                    message: user_id invalid value
                wallet_id_invalid:
                  summary: Wallet ID value is invalid
                  value:
                    code: wallet_id_value_invalid
                    type: validation_error
                    message: wallet_id invalid value
                card_id_invalid:
                  summary: Card ID value is invalid
                  value:
                    code: card_id_invalid
                    type: validation_error
                    message: card_id is invalid in the request
                userWalletMismatch:
                  summary: User-Wallet mismatch
                  value:
                    message: wallet does not belong to provided user
                    code: wallet_id_value_invalid
                    type: validation_error
                userCardMismatch:
                  summary: User-Card mismatch
                  value:
                    message: card does not belong to provided user
                    code: card_id_value_invalid
                    type: validation_error
                userSubWalletMismatch:
                  summary: User-SubWallet mismatch
                  value:
                    message: sub-wallet does not belong to provided user
                    code: sub_wallet_id_value_invalid
                    type: validation_error
                sub_wallet_id_invalid:
                  summary: Sub-wallet ID is invalid
                  value:
                    code: sub_wallet_id_invalid
                    type: validation_error
                    message: cf_sub_wallet_id is invalid in the request
                missingClientId:
                  summary: Missing client ID
                  value:
                    message: x-client-id is missing in the request
                    code: x-client-id_missing
                    type: validation_error
                missingClientSecret:
                  summary: Missing client secret
                  value:
                    message: x-client-secret is missing in the request
                    code: x-client-secret_missing
                    type: validation_error
        '401':
          $ref: '#/components/responses/Response401'
        '403':
          $ref: '#/components/responses/Response403'
        '404':
          description: The requested resource was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StructuredErrorResponse'
              examples:
                cardNotFound:
                  summary: Card not found
                  value:
                    code: card_id_not_found
                    type: validation_error
                    message: card_id with given id not found
                userNotFound:
                  summary: User not found
                  value:
                    code: user_id_not_found
                    type: invalid_request_error
                    message: The specified user_id does not exist
                walletNotFound:
                  summary: Wallet not found
                  value:
                    code: wallet_not_found
                    type: validation_error
                    message: No wallet found with the provided wallet_id
                subWalletNotFound:
                  summary: Sub-wallet not found
                  value:
                    code: sub_wallet_not_found
                    type: validation_error
                    message: No sub-wallet found with the provided cf_sub_wallet_id
        '429':
          $ref: '#/components/responses/Response429'
        '500':
          $ref: '#/components/responses/Response500'
      security:
        - XClientID: []
          XClientSecret: []
components:
  parameters:
    global_x_api_version:
      description: API version to be used. Format is in YYYY-MM-DD.
      name: x-api-version
      in: header
      required: true
      schema:
        type: string
        default: '2025-11-01'
        example: '2025-11-01'
      example: '2025-11-01'
  schemas:
    FetchWalletBalanceRequest:
      type: object
      required:
        - user_id
        - wallet_id or card_id
      properties:
        user_id:
          type: string
          description: >-
            Unique identifier for the user, as provided by you during PPI user
            creation.
          example: USER827364
        wallet_id:
          type: string
          description: >-
            Unique identifier for the wallet, as provided by you during wallet
            creation.
          example: WALLET936721
        card_id:
          type: string
          description: >-
            Unique identifier for the card, as provided by you during card
            creation.
          example: CARDR827364
        cf_sub_wallet_id:
          type: string
          description: >-
            Optional sub-wallet ID. If provided, the response includes only this
            sub-wallet's balance.
          example: '35246543210987654321'
    StructuredErrorResponse:
      type: object
      properties:
        type:
          type: string
          description: A broad category of the error.
          example: internal_error
        code:
          type: string
          description: A machine-readable error code specific to the issue.
          example: internal_server_error
        message:
          type: string
          description: >-
            A message providing more details about the error, dynamic based on
            the specific issue.
          example: Internal server error
    FetchWalletBalanceResponse:
      type: object
      properties:
        user_id:
          type: string
          description: >-
            Unique identifier for the user, as provided by you during PPI user
            creation.
          example: USER827364
        cf_program_id:
          type: string
          description: >-
            Unique identifier of the PPI program associated with the wallet, as
            provided by Cashfree.
          example: '9876543210987654321'
        wallet_id:
          type: string
          description: >-
            Unique identifier for the wallet, as provided by you during wallet
            creation.
          example: WALLET936721
        cf_wallet_id:
          type: string
          description: >-
            Unique identifier for the wallet, automatically generated by
            Cashfree after successful wallet creation.
          example: '1234567890123456783'
        wallet_name:
          type: string
          description: Name of the wallet.
          example: Cashback Wallet
        sub_wallets:
          type: array
          description: List of sub-wallets created for this wallet.
          items:
            $ref: '#/components/schemas/FetchWalletBalanceSubWallet'
        card:
          $ref: '#/components/schemas/WalletCardDetails'
    FetchWalletBalanceSubWallet:
      type: object
      properties:
        cf_sub_wallet_id:
          type: string
          description: >-
            Unique identifier for the sub-wallet, returned when the wallet is
            created.
          example: '5432109876543210987'
        name:
          type: string
          description: Name of the sub-wallet.
          example: Gift Wallet
        type:
          type: string
          description: Type of the sub-wallet.
          example: GIFT_PPI
        status:
          type: string
          description: Status of the sub-wallet.
          example: ACTIVE
        balance:
          type: number
          format: double
          description: Current balance of the sub-wallet.
          example: 0
        available_balance:
          type: number
          format: double
          description: Available balance in the sub-wallet.
          example: 0
        funds_on_hold:
          type: number
          format: double
          description: Funds on hold in the sub-wallet.
          example: 0
    WalletCardDetails:
      type: object
      description: Card details associated with the wallet, if a card exists.
      properties:
        card_name:
          type: string
          description: Name of the card.
          example: Cashfree Pay
        card_id:
          type: string
          description: >-
            Unique identifier for the card, as provided by you during card
            creation.
          example: CARDR827364
        cf_card_id:
          type: string
          description: Unique identifier for the card, generated by Cashfree.
          example: '1410908340461592576'
        masked_card_number:
          type: string
          description: Masked card number.
          example: XXXXXXXXXXXX0185
        name_on_card:
          type: string
          description: Name printed on the card.
          example: John Doe
        card_holder_name:
          type: string
          description: Name of the cardholder.
          example: John Doe
        card_network:
          type: string
          description: Card network.
          example: RUPAY
        status:
          type: string
          description: |
            Status of the card:
            - `ACTIVE`: Card is active and can be used for transactions.
            - `LOCKED`: Card is locked and cannot be used for transactions.
          enum:
            - ACTIVE
            - LOCKED
          example: ACTIVE
  responses:
    FetchWalletBalanceResponse:
      description: Success response for fetching wallet details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FetchWalletBalanceResponse'
          examples:
            SUCCESS_BY_WALLET_HAVING_NO_CARD:
              summary: Wallet details fetched by wallet ID (no associated card)
              value:
                user_id: USER827364
                cf_program_id: '9876543210987654321'
                wallet_id: WALLET936721
                cf_wallet_id: '1234567890123456783'
                wallet_name: Gift Wallet
                sub_wallets:
                  - cf_sub_wallet_id: '35246543210987654321'
                    name: Gift Wallet
                    type: GIFT_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
                  - cf_sub_wallet_id: '54252453468535350359'
                    name: Cashfree Wallet
                    type: CLOSED_LOOP_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
            SUCCESS_BY_WALLET_HAVING_CARD:
              summary: Wallet details fetched by wallet ID (with associated card)
              value:
                user_id: USER827364
                cf_program_id: '9876543210987654321'
                wallet_id: WALLET936721
                cf_wallet_id: '1234567890123456783'
                wallet_name: Cashfree Wallet
                sub_wallets:
                  - cf_sub_wallet_id: '35246543210987654321'
                    name: Meal Wallet
                    type: STANDARD_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
                  - cf_sub_wallet_id: '54252453468535350359'
                    name: Fuel Wallet
                    type: STANDARD_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
                card:
                  card_name: Cashfree Pay
                  card_id: CARDR827364
                  cf_card_id: '1410908340461592576'
                  masked_card_number: XXXXXXXXXXXX0185
                  name_on_card: John Doe
                  card_holder_name: John Doe
                  card_network: RUPAY
                  status: ACTIVE
            SUCCESS_BY_CARD:
              summary: Wallet details fetched by card ID
              value:
                user_id: USER827364
                cf_program_id: '9876543210987654321'
                wallet_id: WALLET936721
                cf_wallet_id: '1234567890123456783'
                wallet_name: Cashfree Wallet
                sub_wallets:
                  - cf_sub_wallet_id: '35246543210987654321'
                    name: Meal Wallet
                    type: STANDARD_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
                  - cf_sub_wallet_id: '54252453468535350359'
                    name: Fuel Wallet
                    type: STANDARD_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
                card:
                  card_name: Cashfree Pay
                  card_id: CARDR827364
                  cf_card_id: '1410908340461592576'
                  masked_card_number: XXXXXXXXXXXX0185
                  name_on_card: John Doe
                  card_holder_name: John Doe
                  card_network: RUPAY
                  status: ACTIVE
            SUCCESS_BY_SUB_WALLET_HAVING_NO_CARD:
              summary: Wallet details fetched by wallet ID and sub-wallet ID
              value:
                user_id: USER827364
                cf_program_id: '9876543210987654321'
                wallet_id: WALLET936721
                cf_wallet_id: '1234567890123456783'
                wallet_name: Gift Wallet
                sub_wallets:
                  - cf_sub_wallet_id: '35246543210987654321'
                    name: Gift Wallet
                    type: GIFT_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
            SUCCESS_BY_SUB_WALLET_HAVING_CARD:
              summary: Wallet details fetched by card ID and sub-wallet ID
              value:
                user_id: USER827364
                cf_program_id: '9876543210987654321'
                wallet_id: WALLET936721
                cf_wallet_id: '1234567890123456783'
                wallet_name: Cashfree Wallet
                sub_wallets:
                  - cf_sub_wallet_id: '35246543210987654321'
                    name: Meal Wallet
                    type: STANDARD_PPI
                    status: ACTIVE
                    balance: 0
                    available_balance: 0
                    funds_on_hold: 0
                card:
                  card_name: Cashfree Pay
                  card_id: CARDR827364
                  cf_card_id: '1410908340461592576'
                  masked_card_number: XXXXXXXXXXXX0185
                  name_on_card: John Doe
                  card_holder_name: John Doe
                  card_network: RUPAY
                  status: ACTIVE
    Response401:
      description: Unauthorised - Invalid or missing authentication.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StructuredErrorResponse'
          examples:
            invalidCredentials:
              summary: Invalid client credentials
              value:
                code: authentication_failed
                type: authentication_error
                message: Invalid client ID and client secret combination
    Response403:
      description: Forbidden - Access denied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StructuredErrorResponse'
          examples:
            ipNotWhitelisted:
              summary: IP not whitelisted
              value:
                code: ip_not_whitelisted
                type: authentication_error
                message: Authentication error (IP not whitelisted)
    Response429:
      description: Too Many Requests - Rate limit exceeded.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StructuredErrorResponse'
          examples:
            internalError:
              summary: Internal server error
              value:
                code: too_many_requests_per_operation
                type: rate_limit_error
                message: Rate limit exceeded. Please try again after some time
    Response500:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/StructuredErrorResponse'
          examples:
            internalError:
              summary: Internal server error
              value:
                code: internal_server_error
                type: internal_error
                message: An internal error occurred while processing the request
  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/merchants/landing?env=prod).
    XClientSecret:
      type: apiKey
      in: header
      name: x-client-secret
      description: >-
        The secret key associated with your client ID. Use this to authenticate
        your API requests. You can find this in your [Merchant
        Dashboard](https://merchant.cashfree.com/merchants/landing?env=prod).

````