Transactions API

Overview

The Transactions API provides access to your complete transaction history, including charges, refunds, transfers, adjustments, and fees. Use this API for accounting, reconciliation, and detailed financial reporting.

Available Endpoints

• List Transactions - GET /transactions
• Retrieve Transaction - GET /transactions/:id

What You Can Do

• View Transaction History - Access complete record of all account activity
• Filter by Date - Retrieve transactions for specific time periods
• Filter by Type - View only charges, refunds, transfers, or fees
• Reconcile Accounts - Match transactions with bank statements
• Generate Reports - Export transaction data for accounting
• Track Balance Changes - See how each transaction affects your balance

Transaction Types

Credit Transactions (Money In)

• Charges - Successful payments from customers
• Dispute Reversals - Won disputes returning funds
• Refund Reversals - Cancelled refunds

Debit Transactions (Money Out)

• Refunds - Money returned to customers
• Transfers - Payouts to bank accounts
• Fees - Transaction and service fees
• Disputes - Chargebacks and disputed amounts
• Adjustments - Account corrections

Transaction Object Structure

{
  "object": "transaction",
  "id": "trxn_test_5xuy4w91xqz7d1w9u0t",
  "type": "credit",
  "amount": 100000,
  "currency": "thb",
  "direction": "credit",
  "source": {
    "object": "charge",
    "id": "chrg_test_5xuy4w91xqz7d1w9u0t"
  },
  "created_at": "2025-02-07T12:00:00Z"
}

Use Cases

Accounting & Reconciliation

Match Omise transactions with your bank statements and internal records:

// Get all transactions for a specific day
const transactions = await omise.transactions.list({
  from: '2025-02-07T00:00:00Z',
  to: '2025-02-07T23:59:59Z',
  limit: 100
});

// Calculate daily totals
let credits = 0;
let debits = 0;

transactions.data.forEach(txn => {
  if (txn.direction === 'credit') {
    credits += txn.amount;
  } else {
    debits += txn.amount;
  }
});

console.log(`Credits: ${credits}, Debits: ${debits}, Net: ${credits - debits}`);

Financial Reporting

Generate monthly reports for accounting:

// Get monthly transaction summary
const monthlyTransactions = await omise.transactions.list({
  from: '2025-02-01T00:00:00Z',
  to: '2025-02-28T23:59:59Z',
  limit: 100
});

// Group by type
const summary = {
  charges: 0,
  refunds: 0,
  transfers: 0,
  fees: 0
};

monthlyTransactions.data.forEach(txn => {
  const sourceType = txn.source?.object;
  if (sourceType === 'charge') summary.charges += txn.amount;
  if (sourceType === 'refund') summary.refunds += txn.amount;
  if (sourceType === 'transfer') summary.transfers += txn.amount;
  // Add more types as needed
});

Balance Verification

Verify your balance calculation:

// Calculate expected balance from transactions
const allTransactions = await getAllTransactions(); // Your pagination logic

let calculatedBalance = 0;
allTransactions.forEach(txn => {
  if (txn.direction === 'credit') {
    calculatedBalance += txn.amount;
  } else {
    calculatedBalance -= txn.amount;
  }
});

const currentBalance = await omise.balance.retrieve();
console.log(`Calculated: ${calculatedBalance}, Actual: ${currentBalance.available}`);

Filtering & Pagination

Date Range Filtering

GET /transactions?from=2025-01-01T00:00:00Z&to=2025-01-31T23:59:59Z

Pagination

GET /transactions?limit=100&offset=0

Combined Filters

GET /transactions?from=2025-02-01T00:00:00Z&limit=50&offset=0

Best Practices

✅ Do This

• Use date ranges - Filter by specific periods for better performance
• Paginate results - Use reasonable page sizes (50-100)
• Cache transaction data - Transactions are immutable, cache for long periods
• Handle timezones - All timestamps are UTC (Z timezone)
• Store transaction IDs - Keep IDs for reconciliation and auditing
• Regular exports - Export monthly for accounting records

❌ Don't Do This

• Don't fetch all transactions - Always use date filters
• Don't poll frequently - Transactions don't change once created
• Don't ignore pagination - Handle large result sets properly
• Don't assume order - Specify order parameter explicitly
• Don't skip reconciliation - Regular checks prevent accounting issues

Common Questions

What's the difference between Transactions and Balance?

• Balance - Current account balance (single point in time)
• Transactions - Historical record of all activity (over time)

How long are transactions stored?

All transactions are stored permanently and accessible via the API.

Can I delete transactions?

No, transactions are immutable audit records and cannot be deleted or modified.

How do I export for accounting software?

Use the List Transactions API with date filters, then format the data for your accounting system (QuickBooks, Xero, etc.).

Related Resources

• List Transactions - GET /transactions
• Retrieve Transaction - GET /transactions/:id
• Balance API - Check current balance
• Charges API - View charges
• Refunds API - View refunds
• Transfers API - View transfers

See Also

• Money Management Guide
• Balance & Reconciliation
• Transaction Reportstransaction-reports)
• Dashboard Transactions

---

Need help? Contact support@omise.co