Skip to main content

Balance & Transactions Overview

Your Omise account balance represents the funds available in your account. This guide explains how to check your balance, understand different balance types, and manage your funds effectively.

Overviewโ€‹

Understanding your account balance is crucial for:

  • Transfer Planning: Knowing available funds for payouts
  • Cash Flow Management: Monitoring incoming and outgoing funds
  • Reconciliation: Matching transactions to bank deposits
  • Financial Planning: Forecasting available funds
  • Operational Decisions: Planning refunds and transfers

Key Conceptsโ€‹

  • Total Balance: All funds in your account (available + pending)
  • Available Balance: Funds available for immediate use
  • Pending Balance: Funds awaiting settlement or processing
  • Transferable Balance: Amount available for transfers after fees
  • Currency: Balance tracked per currency

Checking Your Balanceโ€‹

Retrieve Current Balanceโ€‹

const omise = require('omise')({
  secretKey: 'skey_test_123456789',
});

// Get current balance
async function getBalance() {
  try {
    const balance = await omise.balance.retrieve();

    console.log('Balance Information:');
    console.log('------------------');
    console.log(`Total: ${balance.total / 100} ${balance.currency.toUpperCase()}`);
    console.log(`Available: ${balance.available / 100} ${balance.currency.toUpperCase()}`);
    console.log(`Currency: ${balance.currency.toUpperCase()}`);
    console.log(`Livemode: ${balance.livemode}`);

    return balance;
  } catch (error) {
    console.error('Failed to retrieve balance:', error.message);
    throw error;
  }
}

// Get detailed balance breakdown
async function getBalanceBreakdown() {
  const balance = await omise.balance.retrieve();
  
  const pending = balance.total - balance.available;
  
  return {
    total: balance.total,
    available: balance.available,
    pending: pending,
    currency: balance.currency,
    breakdown: {
      total_formatted: `${balance.total / 100} ${balance.currency.toUpperCase()}`,
      available_formatted: `${balance.available / 100} ${balance.currency.toUpperCase()}`,
      pending_formatted: `${pending / 100} ${balance.currency.toUpperCase()}`
    }
  };
}

// Check if sufficient balance for operation
async function hasSufficientBalance(requiredAmount) {
  const balance = await omise.balance.retrieve();
  
  return {
    sufficient: balance.available >= requiredAmount,
    available: balance.available,
    required: requiredAmount,
    shortfall: Math.max(0, requiredAmount - balance.available)
  };
}

// Example usage
getBalance();
getBalanceBreakdown().then(breakdown => console.log(breakdown));
hasSufficientBalance(100000).then(result => {
  if (result.sufficient) {
    console.log('โœ“ Sufficient balance');
  } else {
    console.log(`โœ— Insufficient balance. Short by ${result.shortfall / 100}`);
  }
});

API Responseโ€‹

{
  "object": "balance",
  "livemode": false,
  "location": "/balance",
  "available": 500000,
  "total": 750000,
  "currency": "thb"
}

Understanding Balance Typesโ€‹

Available vs Total Balanceโ€‹

// Available Balance: Ready to use immediately
// Total Balance: Available + Pending funds

function explainBalance(balance) {
  const pending = balance.total - balance.available;
  
  console.log('Balance Explanation:');
  console.log(`Total Balance: ${balance.total / 100} ${balance.currency.toUpperCase()}`);
  console.log(`  โ”œโ”€ Available: ${balance.available / 100} (ready to use)`);
  console.log(`  โ””โ”€ Pending: ${pending / 100} (being processed)`);
  
  console.log('\nWhat you can do:');
  console.log(`  โ€ข Create transfers up to: ${balance.available / 100}`);
  console.log(`  โ€ข Create refunds up to: ${balance.available / 100}`);
  console.log(`  โ€ข Pending will become available after settlement`);
}

Pending Balanceโ€‹

Pending balance includes:

  • Recent charges awaiting settlement
  • In-process refunds
  • Transfers being processed
  • Disputed charges held
def analyze_pending_balance():
    """Analyze why funds are pending"""
    balance = omise.Balance.retrieve()
    pending = balance.total - balance.available
    
    if pending > 0:
        print(f"Pending Balance: {pending / 100:.2f} {balance.currency.upper()}")
        print("\nPossible reasons for pending funds:")
        print("  โ€ข Recent charges awaiting settlement (1-2 days)")
        print("  โ€ข Refunds being processed")
        print("  โ€ข Transfers in progress")
        print("  โ€ข Disputed transactions on hold")
        print("\nThese funds will become available after settlement.")
    else:
        print("No pending funds. All balance is available.")

Balance Monitoringโ€‹

Real-time Monitoringโ€‹

class BalanceMonitor {
  constructor(thresholds) {
    this.thresholds = thresholds || {
      low: 100000,    // 1,000 THB
      critical: 50000  // 500 THB
    };
  }
  
  async checkBalance() {
    const balance = await omise.balance.retrieve();
    
    const status = {
      current: balance.available,
      status: this.getBalanceStatus(balance.available),
      alerts: []
    };
    
    if (balance.available <= this.thresholds.critical) {
      status.alerts.push({
        level: 'critical',
        message: `Critical: Balance at ${balance.available / 100} ${balance.currency.toUpperCase()}`
      });
      await this.notifyCriticalBalance(balance);
    } else if (balance.available <= this.thresholds.low) {
      status.alerts.push({
        level: 'warning',
        message: `Warning: Low balance at ${balance.available / 100} ${balance.currency.toUpperCase()}`
      });
      await this.notifyLowBalance(balance);
    }
    
    return status;
  }
  
  getBalanceStatus(available) {
    if (available <= this.thresholds.critical) return 'critical';
    if (available <= this.thresholds.low) return 'low';
    return 'healthy';
  }
  
  async notifyCriticalBalance(balance) {
    console.log('๐Ÿšจ CRITICAL: Balance very low!');
    // Send urgent notification
  }
  
  async notifyLowBalance(balance) {
    console.log('โš ๏ธ  WARNING: Balance is low');
    // Send warning notification
  }
}

// Usage
const monitor = new BalanceMonitor({
  low: 100000,
  critical: 50000
});

setInterval(async () => {
  const status = await monitor.checkBalance();
  console.log('Balance Status:', status.status);
}, 3600000); // Check every hour

Common Use Casesโ€‹

1. Pre-Operation Balance Checkโ€‹

class BalanceGuard:
    def __init__(self, buffer_amount=0):
        self.buffer_amount = buffer_amount
    
    def can_perform_operation(self, operation_type, amount):
        """Check if operation can be performed"""
        balance = omise.Balance.retrieve()
        
        # Calculate required amount based on operation
        if operation_type == 'transfer':
            # Transfer + fee
            required = amount + 2500  # 25 THB fee
        elif operation_type == 'refund':
            required = amount
        else:
            required = amount
        
        # Add buffer
        required += self.buffer_amount
        
        if balance.available < required:
            return {
                'allowed': False,
                'reason': 'insufficient_balance',
                'available': balance.available,
                'required': required,
                'shortfall': required - balance.available
            }
        
        return {
            'allowed': True,
            'available': balance.available,
            'required': required,
            'remaining_after': balance.available - required
        }

# Usage
guard = BalanceGuard(buffer_amount=10000)  # Keep 100 THB buffer
check = guard.can_perform_operation('transfer', 100000)

if check['allowed']:
    print(f"โœ“ Can proceed. Will have {check['remaining_after']/100:.2f} remaining")
else:
    print(f"โœ— Cannot proceed. Short by {check['shortfall']/100:.2f}")

2. Daily Balance Reportโ€‹

class DailyBalanceReport
  def generate_report
    balance = Omise::Balance.retrieve
    
    report = {
      date: Date.today.to_s,
      balance: {
        total: balance.total,
        available: balance.available,
        pending: balance.total - balance.available,
        currency: balance.currency
      },
      formatted: format_balance(balance),
      status: assess_balance_health(balance),
      recommendations: get_recommendations(balance)
    }
    
    print_report(report)
    save_report(report)
    
    report
  end
  
  def format_balance(balance)
    {
      total: "#{balance.total / 100.0} #{balance.currency.upcase}",
      available: "#{balance.available / 100.0} #{balance.currency.upcase}",
      pending: "#{(balance.total - balance.available) / 100.0} #{balance.currency.upcase}"
    }
  end
  
  def assess_balance_health(balance)
    case balance.available
    when 0..50000
      'critical'
    when 50001..100000
      'low'
    when 100001..500000
      'moderate'
    else
      'healthy'
    end
  end
  
  def get_recommendations(balance)
    recommendations = []
    
    if balance.available < 100000
      recommendations << "Consider adding funds"
    end
    
    pending = balance.total - balance.available
    if pending > balance.available * 2
      recommendations << "High pending balance - review settlements"
    end
    
    recommendations
  end
  
  def print_report(report)
    puts "\n#{'='*50}"
    puts "DAILY BALANCE REPORT - #{report[:date]}"
    puts "="*50
    puts "Total:     #{report[:formatted][:total]}"
    puts "Available: #{report[:formatted][:available]}"
    puts "Pending:   #{report[:formatted][:pending]}"
    puts "Status:    #{report[:status].upcase}"
    
    unless report[:recommendations].empty?
      puts "\nRecommendations:"
      report[:recommendations].each { |r| puts "  โ€ข #{r}" }
    end
    puts "="*50
  end
  
  def save_report(report)
    # Save to file or database
    File.open('balance_reports.log', 'a') do |f|
      f.puts JSON.generate(report)
    end
  end
end

Best Practicesโ€‹

1. Always Check Balance Before Operationsโ€‹

async function safeOperation(operationType, amount) {
  const balance = await omise.balance.retrieve();
  
  // Calculate required amount
  let required = amount;
  if (operationType === 'transfer') {
    required += 2500; // Add transfer fee
  }
  
  // Check balance
  if (balance.available < required) {
    throw new Error(`Insufficient balance: need ${required}, have ${balance.available}`);
  }
  
  // Proceed with operation
  console.log(`โœ“ Sufficient balance. Proceeding with ${operationType}`);
  return true;
}

2. Monitor Balance Regularlyโ€‹

import schedule
import time

def monitor_balance():
    """Scheduled balance monitoring"""
    balance = omise.Balance.retrieve()
    
    if balance.available < 50000:
        send_alert(f"Critical: Balance at {balance.available/100:.2f}")
    elif balance.available < 100000:
        send_notification(f"Warning: Low balance at {balance.available/100:.2f}")

# Run every hour
schedule.every().hour.do(monitor_balance)

while True:
    schedule.run_pending()
    time.sleep(60)

3. Maintain Buffer Amountโ€‹

function maintainBalanceBuffer($operationAmount, $bufferAmount = 10000) {
    $balance = OmiseBalance::retrieve();
    
    $required = $operationAmount + $bufferAmount;
    
    if ($balance['available'] < $required) {
        throw new Exception("Insufficient balance including buffer");
    }
    
    echo "โœ“ Sufficient balance with buffer maintained\n";
    return true;
}

FAQโ€‹

What's the difference between available and total balance?โ€‹

Available balance is the amount you can use immediately for transfers and refunds. Total balance includes both available and pending funds (charges awaiting settlement, refunds in progress, etc.).

How long does it take for pending balance to become available?โ€‹

Typically 1-2 business days. The exact timing depends on your settlement schedule and the type of transaction.

Can I use pending balance for transfers?โ€‹

No, only available balance can be used for transfers and refunds. Pending funds must settle first.

Why is my available balance less than I expected?โ€‹

Common reasons include:

  • Recent transfers deducted from balance
  • Refunds processed
  • Pending settlements not yet cleared
  • Reserve requirements (if applicable)
  • Disputes holding funds

How often should I check my balance?โ€‹

For high-volume businesses, check before each major operation. Implement automated monitoring to alert you when balance drops below thresholds.

Can I have negative balance?โ€‹

No, operations requiring more than your available balance will fail. Always check balance before operations.

What currency is my balance in?โ€‹

Balance is tracked per currency. Multi-currency accounts will have separate balances for each currency (THB, USD, etc.).

How do I add funds to my balance?โ€‹

Your balance increases automatically as you receive successful charges from customers. It decreases when you issue refunds or create transfers.

Next Stepsโ€‹