Skip to main content
POST/payout/v1/balance

Wallet 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

AttributeDetails
MethodGET
URLhttps://merchant.paywize.in/api/payout/v1/balance
AuthenticationBearer token required
Content-Typeapplication/json
Response FormatDirect JSON (not encrypted)
Rate Limit500 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

ParameterRequiredTypeDescription
wallet_idYesStringMerchant 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

FieldDescription
available_balanceAvailable wallet balance
updated_atLast update timestamp for the balance (ISO 8601 format)

Error Responses

Success Response

CodeMessage
2000Wallet balance fetched successfully

Client Error Responses

CodeMessageDescription
4022Bad request, wallet_id is requiredMissing wallet_id query parameter
CodeMessageDescription
4044Wallet not foundProvided wallet_id does not exist or is invalid

Server Error Responses

CodeMessageDescription
5000Internal server errorUnexpected 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

  1. Pre-transaction Validation: Always check balance before initiating payouts
  2. Regular Monitoring: Monitor balance regularly to avoid transaction failures
  3. Low Balance Alerts: Set up alerts when balance falls below threshold
  4. Error Handling: Implement proper error handling for balance check failures
  5. Token Management: Ensure your JWT token is valid and refresh if expired
  6. Balance History: Track balance changes over time for better financial management
  7. Security: Never log decrypted balance information

Balance Top-up

To add funds to your wallet:

  1. Bank Transfer: Transfer funds to your designated Paywize account
  2. Online Banking: Use net banking for instant credit
  3. NEFT/RTGS: Use traditional bank transfer methods
  4. Cheque Deposit: Physical cheque deposits (T+1 processing)

Contact support for wallet top-up assistance:

Next Steps