メインコンテンツへスキップ

Balance & Transactions 概要

Omiseアカウントのbalanceは、アカウント内で利用可能な資金を表します。このガイドでは、balanceの確認方法、さまざまなbalanceタイプの理解、および資金を効果的に管理する方法について説明します。

概要​

アカウントbalanceの理解は以下の目的で重要です:

  • Transfer計画: 支払いに利用可能な資金の把握
  • キャッシュフロー管理: 入出金の監視
  • Reconciliation: transactionと銀行入金の照合
  • 財務計画: 利用可能資金の予測
  • 運用上の意思決定: refundとtransferの計画

主要な概念​

  • Total Balance: アカウント内の全資金（available + pending）
  • Available Balance: 即座に使用可能な資金
  • Pending Balance: settlement待ちまたは処理中の資金
  • Transferable Balance: 手数料控除後の送金可能金額
  • Currency: 通貨ごとに追跡されるbalance

Balanceの確認​

現在のBalanceの取得​

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

// 現在のbalanceを取得
async function getBalance() {
  try {
    const balance = await omise.balance.retrieve();

    console.log('Balance情報:');
    console.log('------------------');
    console.log(`合計: ${balance.total / 100} ${balance.currency.toUpperCase()}`);
    console.log(`利用可能: ${balance.available / 100} ${balance.currency.toUpperCase()}`);
    console.log(`通貨: ${balance.currency.toUpperCase()}`);
    console.log(`ライブモード: ${balance.livemode}`);

    return balance;
  } catch (error) {
    console.error('Balanceの取得に失敗しました:', error.message);
    throw error;
  }
}

// 詳細なbalance内訳を取得
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()}`
    }
  };
}

// 操作に十分なbalanceがあるか確認
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)
  };
}

// 使用例
getBalance();
getBalanceBreakdown().then(breakdown => console.log(breakdown));
hasSufficientBalance(100000).then(result => {
  if (result.sufficient) {
    console.log('✓ 残高は十分です');
  } else {
    console.log(`✗ 残高が不足しています。不足額: ${result.shortfall / 100}`);
  }
});

APIレスポンス​

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

Balanceタイプの理解​

Available BalanceとTotal Balance​

// Available Balance: すぐに使用可能
// Total Balance: Available + Pending資金

function explainBalance(balance) {
  const pending = balance.total - balance.available;

  console.log('Balance説明:');
  console.log(`Total Balance: ${balance.total / 100} ${balance.currency.toUpperCase()}`);
  console.log(`  ├─ Available: ${balance.available / 100} (使用可能)`);
  console.log(`  └─ Pending: ${pending / 100} (処理中)`);

  console.log('\n実行可能な操作:');
  console.log(`  • 最大 ${balance.available / 100} までのtransferを作成`);
  console.log(`  • 最大 ${balance.available / 100} までのrefundを作成`);
  console.log(`  • Pendingはsettlement後にavailableになります`);
}

Pending Balance​

Pending balanceには以下が含まれます:

  • settlement待ちの最近のcharge
  • 処理中のrefund
  • 処理中のtransfer
  • 保留中の異議申し立てcharge
def analyze_pending_balance():
    """Pending資金の理由を分析"""
    balance = omise.Balance.retrieve()
    pending = balance.total - balance.available

    if pending > 0:
        print(f"Pending Balance: {pending / 100:.2f} {balance.currency.upper()}")
        print("\nPending資金の考えられる理由:")
        print("  • Settlement待ちの最近のcharge（1〜2日）")
        print("  • 処理中のrefund")
        print("  • 処理中のtransfer")
        print("  • 保留中の異議申し立てtransaction")
        print("\nこれらの資金はsettlement後にavailableになります。")
    else:
        print("Pending資金はありません。すべてのbalanceが利用可能です。")

Balance監視​

リアルタイム監視​

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: `緊急: 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: `警告: 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('🚨 緊急: Balanceが非常に少ない!');
    // 緊急通知を送信
  }

  async notifyLowBalance(balance) {
    console.log('⚠️  警告: Balanceが少ない');
    // 警告通知を送信
  }
}

// 使用方法
const monitor = new BalanceMonitor({
  low: 100000,
  critical: 50000
});

setInterval(async () => {
  const status = await monitor.checkBalance();
  console.log('Balanceステータス:', status.status);
}, 3600000); // 1時間ごとにチェック

一般的なユースケース​

1. 操作前のBalance確認​

class BalanceGuard:
    def __init__(self, buffer_amount=0):
        self.buffer_amount = buffer_amount

    def can_perform_operation(self, operation_type, amount):
        """操作を実行できるか確認"""
        balance = omise.Balance.retrieve()

        # 操作タイプに基づいて必要な金額を計算
        if operation_type == 'transfer':
            # Transfer + fee
            required = amount + 2500  # 25 THB fee
        elif operation_type == 'refund':
            required = amount
        else:
            required = amount

        # バッファを追加
        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
        }

# 使用方法
guard = BalanceGuard(buffer_amount=10000)  # 100 THBのバッファを保持
check = guard.can_perform_operation('transfer', 100000)

if check['allowed']:
    print(f"✓ 実行可能。残高 {check['remaining_after']/100:.2f} が残ります")
else:
    print(f"✗ 実行不可。{check['shortfall']/100:.2f} 不足しています")

2. 日次Balanceレポート​

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 << "資金の追加を検討してください"
    end

    pending = balance.total - balance.available
    if pending > balance.available * 2
      recommendations << "Pending balanceが高い - settlementを確認してください"
    end

    recommendations
  end

  def print_report(report)
    puts "\n#{'='*50}"
    puts "日次BALANCEレポート - #{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 "\n推奨事項:"
      report[:recommendations].each { |r| puts "  • #{r}" }
    end
    puts "="*50
  end

  def save_report(report)
    # ファイルまたはデータベースに保存
    File.open('balance_reports.log', 'a') do |f|
      f.puts JSON.generate(report)
    end
  end
end

ベストプラクティス​

1. 操作前に常にBalanceを確認​

async function safeOperation(operationType, amount) {
  const balance = await omise.balance.retrieve();

  // 必要な金額を計算
  let required = amount;
  if (operationType === 'transfer') {
    required += 2500; // Transfer手数料を追加
  }

  // Balanceをチェック
  if (balance.available < required) {
    throw new Error(`残高不足: 必要 ${required}, 保有 ${balance.available}`);
  }

  // 操作を続行
  console.log(`✓ 十分なbalance。${operationType}を実行します`);
  return true;
}

2. Balanceを定期的に監視​

import schedule
import time

def monitor_balance():
    """スケジュールされたbalance監視"""
    balance = omise.Balance.retrieve()

    if balance.available < 50000:
        send_alert(f"緊急: Balance at {balance.available/100:.2f}")
    elif balance.available < 100000:
        send_notification(f"警告: Low balance at {balance.available/100:.2f}")

# 1時間ごとに実行
schedule.every().hour.do(monitor_balance)

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

3. バッファ金額を維持​

function maintainBalanceBuffer($operationAmount, $bufferAmount = 10000) {
    $balance = OmiseBalance::retrieve();

    $required = $operationAmount + $bufferAmount;

    if ($balance['available'] < $required) {
        throw new Exception("バッファを含む残高が不足しています");
    }

    echo "✓ バッファを維持した十分なbalance\n";
    return true;
}

FAQ​

Available balanceとtotal balanceの違いは何ですか？​

Available balanceは、transferやrefundにすぐに使用できる金額です。Total balanceには、availableとpending資金（settlement待ちのcharge、処理中のrefundなど）の両方が含まれます。

Pending balanceがavailableになるまでどのくらいかかりますか？​

通常1〜2営業日です。正確なタイミングは、settlementスケジュールとtransactionの種類によって異なります。

Pending balanceをtransferに使用できますか？​

いいえ、available balanceのみがtransferとrefundに使用できます。Pending資金は最初にsettleする必要があります。

Available balanceが予想より少ないのはなぜですか？​

一般的な理由:

  • Balanceから差し引かれた最近のtransfer
  • 処理されたrefund
  • まだクリアされていないpending settlement
  • 準備金要件（該当する場合）
  • 資金を保留している異議申し立て

Balanceをどのくらいの頻度で確認すべきですか？​

取引量の多いビジネスの場合、各主要な操作の前に確認してください。Balanceがしきい値を下回ったときに通知する自動監視を実装してください。

Balanceがマイナスになることはありますか？​

いいえ、available balance以上を必要とする操作は失敗します。操作の前に常にbalanceを確認してください。

Balanceの通貨は何ですか？​

Balanceは通貨ごとに追跡されます。マルチカレンシーアカウントは、各通貨（THB、USDなど）で個別のbalanceを持ちます。

Balanceに資金を追加するにはどうすればよいですか？​

Balanceは、顧客からの成功したchargeを受け取ると自動的に増加します。RefundやTransferを作成すると減少します。

関連リソース​

次のステップ​