> 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.