Version: 2019-05-29 (Current)

Balance API

Overview

The Balance API allows you to retrieve your current account balance, including available funds, pending amounts, and transferable balances across all supported currencies.

Available Endpoint

Retrieve Balance - GET /balance

What You Can Do

Check Available Balance - See how much money is available for transfers
View Pending Amounts - Monitor funds that are pending settlement
Multi-Currency Support - View balances across THB, JPY, SGD, MYR, USD, and more
Real-Time Data - Get up-to-date balance information
Transferable Amounts - Check how much can be transferred to bank accounts

How Balance Works

Balance Types

Your Omise account has three types of balances:

Total Balance - All funds in your account (available + pending)
Available Balance - Funds available for immediate transfer
Transferable Balance - Funds that can be transferred to bank accounts

When Balance Updates

Your balance updates when:

✅ A charge is successfully completed
✅ A refund is processed
✅ A transfer is created
✅ Fees are deducted
✅ Disputes are won or lost
✅ Chargebacks are processed

Settlement Periods

Different payment methods have different settlement periods:

Credit Cards: Usually 2-3 business days
PromptPay: Instant
Mobile Banking: 1-2 business days
Installments: Per installment schedule

Use Cases

Monitor Cash Flow

Check your available balance before initiating transfers to ensure sufficient funds.

Multi-Currency Management

View balances across different currencies if you accept payments in multiple currencies.

Reconciliation

Compare API balance with bank statements and dashboard for accounting purposes.

Automated Transfers

Check transferable balance before creating automatic transfer schedules.

Balance Object Structure

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

Best Practices

✅ Do This

Check before transfers - Verify available balance before creating transfers
Monitor regularly - Set up automated balance monitoring
Handle multiple currencies - Account for different currency balances
Cache appropriately - Balance data can be cached for 1-5 minutes
Use webhooks - Listen for charge.complete and transfer.create events

❌ Don't Do This

Don't poll excessively - Avoid checking balance more than once per minute
Don't assume immediate availability - Account for settlement periods
Don't ignore reserves - Consider reserve requirements for your account
Don't forget pending amounts - Remember that total includes pending funds

Retrieve Balance - Get current balance
Transactions API - View transaction history
Transfers API - Create transfers
Charges API - View charges that affect balance

Overview​

Available Endpoint​

What You Can Do​

How Balance Works​

Balance Types​

When Balance Updates​

Settlement Periods​

Use Cases​

Monitor Cash Flow​

Multi-Currency Management​

Reconciliation​

Automated Transfers​

Balance Object Structure​

Best Practices​

✅ Do This​

❌ Don't Do This​

Related Resources​

See Also​