> For the complete documentation index, see [llms.txt](https://developers.kwikpaisa.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.kwikpaisa.com/v3-guide/payout-integration/balance-inquiry.md).

# Balance Inquiry

Use the Balance Inquiry API to fetch the available payout wallet balance linked to your KwikPaisa merchant account.

This API helps merchants:

* Check available payout balance
* Validate wallet funds before initiating payouts
* Monitor payout account liquidity
* Prevent insufficient balance payout failures

The Balance Inquiry API should be used before initiating bulk or high-value payouts.

***

## Endpoint

```http
POST /api/v3/payout/balance
```

#### To view all available base URLs and environments, refer to:

➡️ [API Resources](/v3-guide/quick-start/api-resources.md)

***

## Authentication required.

Refer to:\
➡️ [Headers](/v3-guide/authentication/headers.md)\
➡️ [Signature Generation](/v3-guide/authentication/signature.md)\
➡️ [Timestamp Validation](/v3-guide/authentication/timestamp.md)

## Request Body

This API does not require any request payload.

```json
{
  "kwikx_wallet_id": "4646464445"
}
```

***

## Example cURL Request

```http
curl --request POST \
--url https://sandbox.kwikpaisa.com/api/v3/payout/balance \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "X-API-KEY: pk_test_xxxxxxxxx" \
--header "X-SIGNATURE: GENERATED_SIGNATURE" \
--header "X-TIMESTAMP: GENERATED_TIMESTAMP" \
--data '{
"kwikx_wallet_id": "4646464445"
}'
```

***

## Example Success Response

```json
{
  "status": true,
  "code": 200,
  "message": "Wallet balance fetched successfully.",
  "data": {
    "environment": "sandbox",
    "wallet_id": "6116229263036",
    "currency": "INR",
    "balance": "99990.00",
    "ip_status": "approved",
    "profile_status": "under_review",
    "account_status": "under_review"
  }
}
```

***

## Response Parameters

| Parameter        | Description                                         |
| ---------------- | --------------------------------------------------- |
| `environment`    | Current API environment (`sandbox` or `production`) |
| `wallet_id`      | Unique merchant wallet ID                           |
| `currency`       | Wallet currency                                     |
| `balance`        | Available wallet balance                            |
| `ip_status`      | Merchant IP whitelist approval status               |
| `profile_status` | Merchant profile verification status                |
| `account_status` | Merchant account review/approval status             |

***

## Recommended Use Cases

Use Balance Inquiry API to:

* Validate payout wallet balance
* Check available funds before payouts
* Monitor operational liquidity
* Prevent payout failures due to insufficient funds

***

## Important Notes

* Balance is returned in real-time
* Currency is currently supported in INR
* Insufficient balance may prevent payout initiation
* Always validate balance before bulk payout processing

***

## Recommended Workflow

1. Check wallet balance
2. Validate available funds
3. Initiate payout transaction
4. Verify payout status using Payout Status API

***

## Common Errors

### 401 Unauthorized

Possible reasons:

* Invalid API key
* Incorrect signature
* Expired timestamp

***

### 403 Access Denied

Possible reasons:

* Merchant not authorized for payouts
* Payout services disabled

***

## Security Recommendations

* Generate signatures server-side only
* Never expose secret keys publicly
* Use HTTPS for all requests
* Validate API responses before processing payouts

***

## Best Practices

* Check balance before every payout batch
* Monitor payout wallet regularly
* Maintain sufficient operational balance
* Implement low-balance alerting systems


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.kwikpaisa.com/v3-guide/payout-integration/balance-inquiry.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.