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

Transactions API

概要​

Transactions APIは、チャージ、返金、送金、調整、手数料を含む完全な取引履歴へのアクセスを提供します。このAPIを会計、照合、詳細な財務レポート作成に使用します。

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

できること​

  • 取引履歴の表示 - すべてのアカウントアクティビティの完全な記録にアクセス
  • 日付でフィルタリング - 特定の期間の取引を取得
  • タイプでフィルタリング - チャージ、返金、送金、または手数料のみを表示
  • アカウントの照合 - 銀行明細書と取引を照合
  • レポートの生成 - 会計用に取引データをエクスポート
  • 残高変更の追跡 - 各取引が残高にどのように影響するかを確認

取引タイプ​

入金取引(受取金)​

  • チャージ - 顧客からの成功した決済
  • 紛争取り消し - 勝訴した紛争による資金返還
  • 返金取り消し - キャンセルされた返金

出金取引(支払金)​

  • 返金 - 顧客への返金
  • 送金 - 銀行口座への支払い
  • 手数料 - 取引およびサービス手数料
  • 紛争 - チャージバックおよび異議申立額
  • 調整 - アカウント修正

Transactionオブジェクトの構造​

{
  "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"
}

ユースケース​

会計と照合​

Omise取引を銀行明細書および内部記録と照合します:

// 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}`);

財務レポート作成​

会計のための月次レポートを生成します:

// 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
});

残高の検証​

残高計算を検証します:

// 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}`);

フィルタリングとページネーション​

日付範囲フィルタリング​

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

ページネーション​

GET /transactions?limit=100&offset=0

組み合わせフィルター​

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

ベストプラクティス​

✅ 推奨事項​

  • 日付範囲を使用 - パフォーマンス向上のために特定の期間でフィルタリング
  • 結果をページ分割 - 妥当なページサイズを使用(50-100)
  • 取引データをキャッシュ - 取引は不変なので長期間キャッシュ可能
  • タイムゾーンを処理 - すべてのタイムスタンプはUTC(Zタイムゾーン)
  • 取引IDを保存 - 照合と監査のためにIDを保持
  • 定期的なエクスポート - 会計記録のために月次エクスポート

❌ 避けるべきこと​

  • すべての取引を取得しない - 常に日付フィルターを使用
  • 頻繁にポーリングしない - 取引は一度作成されたら変更されません
  • ページネーションを無視しない - 大きな結果セットを適切に処理
  • 順序を仮定しない - 順序パラメータを明示的に指定
  • 照合をスキップしない - 定期的なチェックで会計問題を防止

よくある質問​

TransactionsとBalanceの違いは何ですか？​

  • Balance - 現在のアカウント残高(単一の時点)
  • Transactions - すべてのアクティビティの履歴記録(時間経過)

取引はどのくらいの期間保存されますか？​

すべての取引は永続的に保存され、API経由でアクセス可能です。

取引を削除できますか？​

いいえ、取引は不変の監査記録であり、削除または変更できません。

会計ソフトウェア用にエクスポートするにはどうすればよいですか？​

日付フィルターを使用してList Transactions APIを使用し、会計システム(QuickBooks、Xeroなど)用にデータをフォーマットします。

関連リソース​

関連情報​

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