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

トランザクション API

概要​

トランザクション APIは、課金、返金、振込、調整、手数料を含む完全な取引履歴へのアクセスを提供します。このAPIを使用して、会計処理、照合、詳細な財務レポートを作成できます。

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

機能​

  • 取引履歴の閲覧 - すべてのアカウントアクティビティの完全な記録にアクセス
  • 日付でフィルタリング - 特定の期間のトランザクションを取得
  • 種類でフィルタリング - 課金、返金、振込、手数料のみを表示
  • アカウントの照合 - トランザクションと銀行明細書を照合
  • レポート生成 - 会計用にトランザクションデータをエクスポート
  • 残高変動の追跡 - 各トランザクションが残高に与える影響を確認

トランザクションの種類​

クレジットトランザクション（入金）​

  • 課金 - 顧客からの決済完了
  • 紛争取消 - 勝訴により返還された資金
  • 返金取消 - キャンセルされた返金

デビットトランザクション（出金）​

  • 返金 - 顧客への返金
  • 振込 - 銀行口座への送金
  • 手数料 - 取引手数料およびサービス手数料
  • 紛争 - チャージバックおよび係争中の金額
  • 調整 - アカウントの修正

トランザクションオブジェクトの構造​

{
  "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のトランザクションを銀行明細書や社内記録と照合します：

// 特定の日のすべてのトランザクションを取得
const transactions = await omise.transactions.list({
  from: '2025-02-07T00:00:00Z',
  to: '2025-02-07T23:59:59Z',
  limit: 100
});

// 日次合計を計算
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}`);

財務レポート​

会計用の月次レポートを生成：

// 月次トランザクションサマリーを取得
const monthlyTransactions = await omise.transactions.list({
  from: '2025-02-01T00:00:00Z',
  to: '2025-02-28T23:59:59Z',
  limit: 100
});

// 種類別にグループ化
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;
  // 必要に応じて他の種類を追加
});

残高の検証​

残高計算を検証：

// トランザクションから期待される残高を計算
const allTransactions = await getAllTransactions(); // ページネーションロジック

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を保持
  • 定期的なエクスポート - 会計記録用に月次でエクスポート

避けるべき事項​

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

よくある質問​

トランザクションと残高の違いは何ですか？​

  • 残高 - 現在のアカウント残高（ある時点の状態）
  • トランザクション - すべてのアクティビティの履歴記録（時系列）

トランザクションはどのくらいの期間保存されますか？​

すべてのトランザクションは永久に保存され、APIからアクセス可能です。

トランザクションを削除できますか？​

いいえ、トランザクションは不変の監査記録であり、削除や変更はできません。

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

日付フィルタ付きでトランザクション一覧APIを使用し、お使いの会計システム（QuickBooks、Xeroなど）に合わせてデータをフォーマットしてください。

関連リソース​

関連ドキュメント​

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