POST
/payout/v1/balanceWallet Balance
Query your Paywize wallet balance in real-time via API.
Last updated: 2026-02-21
Wallet Balance
Overview
Check your current wallet balance to ensure sufficient funds before initiating payouts. This endpoint provides real-time balance information.
Quick Reference
| Attribute | Details |
|---|---|
| Method | GET |
| URL | https://merchant.paywize.in/api/payout/v1/balance |
| Authentication | Bearer token required |
| Content-Type | application/json |
| Response Format | Direct JSON (not encrypted) |
| Rate Limit | 500 requests/minute |
Endpoint
Authentication Required: Bearer token
Authentication
This endpoint requires a valid JWT Bearer token. Learn how to generate tokens: Authentication Guide →
Request Headers
Content-Type: application/json
Authorization: Bearer <jwt_token>
Query Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| wallet_id | Yes | String | Merchant virtual account number |
Sample Request
GET https://merchant.paywize.in/api/payout/v1/balance?wallet_id=PAYWIZE12345679
Response
Success Response (200 OK)
{
"resp_code": 2000,
"resp_message": "Wallet balance fetched successfully",
"data": {
"available_balance": "50000.00",
"updated_at": "2025-11-05T12:30:15Z"
}
}
Note: This endpoint returns the balance data directly (not encrypted), showing the available balance.
Response Fields
| Field | Description |
|---|---|
| available_balance | Available wallet balance |
| updated_at | Last update timestamp for the balance (ISO 8601 format) |
Error Responses
Success Response
| Code | Message |
|---|---|
2000 | Wallet balance fetched successfully |
Client Error Responses
| Code | Message | Description |
|---|---|---|
4022 | Bad request, wallet_id is required | Missing wallet_id query parameter |
| Code | Message | Description |
|---|---|---|
4044 | Wallet not found | Provided wallet_id does not exist or is invalid |
Server Error Responses
| Code | Message | Description |
|---|---|---|
5000 | Internal server error | Unexpected server error occurred |
Implementation Examples
JavaScript
async function checkWalletBalance(token, walletId) {
const response = await fetch(`https://merchant.paywize.in/api/payout/v1/balance?wallet_id=${walletId}`, {
method: 'GET',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
}
});
const result = await response.json();
if (result.resp_code === 2000) {
return result.data;
} else {
throw new Error(`API Error ${result.resp_code}: ${result.resp_message}`);
}
}
// Usage
try {
const walletBalance = await checkWalletBalance(jwtToken, 'PAYWIZE12345679');
console.log('Wallet Balance:', walletBalance);
console.log('Available Balance: ₹', walletBalance.available_balance);
// Check if sufficient balance for a transaction
const transactionAmount = 1000.00;
if (parseFloat(walletBalance.available_balance) >= transactionAmount) {
console.log('✅ Sufficient balance for transaction');
} else {
console.log('❌ Insufficient balance for transaction');
}
} catch (error) {
console.error('Balance check failed:', error.message);
}
Python
import requests
import json
from encryption_utils import decrypt_merchant_data
def check_wallet_balance(token, wallet_id):
response = requests.get(
f'https://merchant.paywize.in/api/payout/v1/balance?wallet_id={wallet_id}',
headers={
'Content-Type': 'application/json',
'Authorization': f'Bearer {token}'
}
)
result = response.json()
if result['resp_code'] == 2000:
return result['data']
else:
raise Exception(f"API Error {result['resp_code']}: {result['resp_message']}")
# Usage
try:
wallet_balance = check_wallet_balance(jwt_token, 'PAYWIZE12345679')
print('Wallet Balance:', wallet_balance)
print(f"Available Balance: ₹{wallet_balance['available_balance']}")
print(f"Updated At: {wallet_balance['updated_at']}")
# Check if sufficient balance for a transaction
transaction_amount = 1000.00
if float(wallet_balance['available_balance']) >= transaction_amount:
print('✅ Sufficient balance for transaction')
else:
print('❌ Insufficient balance for transaction')
except Exception as error:
print('Balance check failed:', str(error))
PHP
<?php
require_once 'PaywizeEncryption.php';
function checkWalletBalance($token, $walletId) {
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://merchant.paywize.in/api/payout/v1/balance?wallet_id=$walletId");
curl_setopt($ch, CURLOPT_HTTPGET, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $token
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
if ($result['resp_code'] == 2000) {
return $result['data'];
} else {
throw new Exception("API Error {$result['resp_code']}: {$result['resp_message']}");
}
}
// Usage
try {
$walletBalance = checkWalletBalance($jwtToken, 'PAYWIZE12345679');
echo "Wallet Balance: " . json_encode($walletBalance) . "\n";
echo "Available Balance: ₹{$walletBalance['available_balance']}\n";
echo "Updated At: {$walletBalance['updated_at']}\n";
// Check if sufficient balance for a transaction
$transactionAmount = 1000.00;
if ((float)$walletBalance['available_balance'] >= $transactionAmount) {
echo "✅ Sufficient balance for transaction\n";
} else {
echo "❌ Insufficient balance for transaction\n";
}
} catch (Exception $error) {
echo "Balance check failed: " . $error->getMessage() . "\n";
}
?>
cURL Example
curl -X GET "https://merchant.paywize.in/api/payout/v1/balance?wallet_id=PAYWIZE12345679" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
Balance Types
Available Balance
- Definition: Balance available for immediate transactions
- Use Case: Check this before initiating payouts
- Calculation: Total balance minus blocked balance
Blocked Balance
- Definition: Balance reserved for pending transactions
- Use Case: Monitor pending transaction amounts
- Duration: Released when transactions complete or fail
Total Balance
- Definition: Sum of available and blocked balance
- Use Case: Overall wallet balance monitoring
- Calculation: Available balance + blocked balance
Balance Validation
Pre-transaction Check
async function validateSufficientBalance(token, transactionAmount, apiKey, secretKey) {
try {
const walletBalance = await checkWalletBalance(token, apiKey, secretKey);
const availableBalance = parseFloat(walletBalance.available_balance);
if (availableBalance >= transactionAmount) {
return {
sufficient: true,
available: availableBalance,
required: transactionAmount,
excess: availableBalance - transactionAmount
};
} else {
return {
sufficient: false,
available: availableBalance,
required: transactionAmount,
shortfall: transactionAmount - availableBalance
};
}
} catch (error) {
throw new Error(`Balance validation failed: ${error.message}`);
}
}
// Usage
const validationResult = await validateSufficientBalance(jwtToken, 1000.00, apiKey, secretKey);
if (validationResult.sufficient) {
console.log(`✅ Sufficient balance. Excess: ₹${validationResult.excess}`);
// Proceed with transaction
} else {
console.log(`❌ Insufficient balance. Shortfall: ₹${validationResult.shortfall}`);
// Request balance top-up or reduce transaction amount
}
Balance Monitoring
Real-time Balance Alerts
class WalletMonitor {
constructor(token, apiKey, secretKey, minBalance = 1000) {
this.token = token;
this.apiKey = apiKey;
this.secretKey = secretKey;
this.minBalance = minBalance;
}
async monitorBalance() {
try {
const balance = await checkWalletBalance(this.token, this.apiKey, this.secretKey);
const availableBalance = parseFloat(balance.available_balance);
if (availableBalance < this.minBalance) {
this.sendLowBalanceAlert(availableBalance);
}
return balance;
} catch (error) {
console.error('Balance monitoring failed:', error.message);
}
}
sendLowBalanceAlert(currentBalance) {
console.log(`🚨 LOW BALANCE ALERT: Current balance ₹${currentBalance} is below minimum threshold ₹${this.minBalance}`);
// Send email, SMS, or push notification
}
}
// Usage
const monitor = new WalletMonitor(jwtToken, apiKey, secretKey, 5000);
const balance = await monitor.monitorBalance();
Best Practices
- Pre-transaction Validation: Always check balance before initiating payouts
- Regular Monitoring: Monitor balance regularly to avoid transaction failures
- Low Balance Alerts: Set up alerts when balance falls below threshold
- Error Handling: Implement proper error handling for balance check failures
- Token Management: Ensure your JWT token is valid and refresh if expired
- Balance History: Track balance changes over time for better financial management
- Security: Never log decrypted balance information
Balance Top-up
To add funds to your wallet:
- Bank Transfer: Transfer funds to your designated Paywize account
- Online Banking: Use net banking for instant credit
- NEFT/RTGS: Use traditional bank transfer methods
- Cheque Deposit: Physical cheque deposits (T+1 processing)
Contact support for wallet top-up assistance:
- Support Email: finance@paywize.in
- Phone: +91-XXXX-XXXXXX
Next Steps
- Initiate Payout with sufficient balance
- Check Transaction Status
- Implement Webhooks for balance updates
- Learn about Authentication
- Learn about Encryption
- View Payout API Overview