メインコンテンツへスキップ
バージョン: 最新版

Balance API

概要​

Balance APIを使用すると、サポートされているすべての通貨での利用可能な資金、保留中の金額、送金可能な残高を含む、現在のアカウント残高を取得できます。

利用可能なエンドポイント​

できること​

  • 利用可能残高の確認 - 送金に利用可能な金額を確認
  • 保留中の金額の表示 - 決済待ちの資金を監視
  • 複数通貨のサポート - THB、JPY、SGD、MYR、USDなど複数通貨での残高を表示
  • リアルタイムデータ - 最新の残高情報を取得
  • 送金可能金額 - 銀行口座に送金できる金額を確認

Balanceの仕組み​

Balanceの種類​

Omiseアカウントには3種類の残高があります：

  1. 総残高 - アカウント内のすべての資金（利用可能＋保留中）
  2. 利用可能残高 - 即座に送金可能な資金
  3. 送金可能残高 - 銀行口座に送金できる資金

残高が更新されるタイミング​

以下の場合に残高が更新されます：

  • ✅ chargeが正常に完了した時
  • ✅ refundが処理された時
  • ✅ transferが作成された時
  • ✅ 手数料が差し引かれた時
  • ✅ disputeが解決された時
  • ✅ chargebackが処理された時

決済期間​

決済方法によって決済期間が異なります：

  • クレジットカード：通常2〜3営業日
  • PromptPay：即時
  • モバイルバンキング：1〜2営業日
  • 分割払い：分割払いスケジュールに従う

使用例​

キャッシュフローの監視​

送金を開始する前に利用可能残高を確認し、十分な資金があることを確認します。

複数通貨の管理​

複数の通貨で決済を受け付ける場合、異なる通貨の残高を表示します。

照合​

会計目的のため、API残高を銀行明細書やdashboardと比較します。

自動送金​

自動送金スケジュールを作成する前に、送金可能残高を確認します。

Balanceオブジェクトの構造​

{
  "object": "balance",
  "livemode": true,
  "available": 1250000,
  "total": 1500000,
  "currency": "thb",
  "transferable": 1200000,
  "reserve": {
    "amount": 50000,
    "percentage": 10.0
  }
}

ベストプラクティス​

✅ 推奨事項​

  • 送金前の確認 - transferを作成する前に利用可能残高を確認
  • 定期的な監視 - 自動残高監視を設定
  • 複数通貨の処理 - 異なる通貨の残高を考慮
  • 適切なキャッシュ - 残高データは1〜5分間キャッシュ可能
  • Webhookの使用 - charge.completeおよびtransfer.createイベントをリッスン

❌ 避けるべき事項​

  • 過度なポーリング - 1分に1回以上の残高確認は避ける
  • 即座の利用可能性の想定 - 決済期間を考慮
  • 準備金の無視 - アカウントの準備金要件を考慮
  • 保留中の金額の忘れ - 総残高には保留中の資金が含まれることを忘れない

関連リソース​

関連情報​

サポートが必要ですか？ support@omise.coまでお問い合わせください