取引データのクエリ

スキーマ内のテーブルにあるデータを、アカウントの残高アクティビティーのレポートに使用します。支払いのテーブルセクション内のテーブルは、支払いや返金など、顧客と Stripe アカウント間の売上の流れを表します。送金のテーブルセクションには、Stripe アカウントの残高から銀行口座への振込 (入金) に関する情報が収録されています。

会計管理の際は、balance_transactions テーブルを開始点として使用します。個別のテーブル ( charges や refunds など) とは異なり、Stripe アカウントの残高を出入りするあらゆるタイプの取引が元帳形式で記録することができます。取引残高を使用して使用頻度の高いレポートを生成し、財務活動に関するレポートの作成を簡素化します。一般的な取引残高のタイプには、以下が含まれます。

• charges
• refunds
• transfers
• payouts
• adjustments
• application_fees

取引残高の各行は、作成後は変更されない個々の balance_transaction オブジェクトを表します。たとえば、支払いを作成すると、タイプ charge で対応する取引残高も作成されます。この支払いを返金した場合は、タイプ refund で取引残高が別個に作成されますが、元の取引残高に変更はありません。同様に、銀行口座での入金の受け取り (振込として表記) についても取引残高が作成されます。

次のクエリ例では、このテーブルを使用して、直近の 5 つの取引残高に関する情報を取得します。

select
  date_format(created, '%m-%d-%Y') as day,
  id,
  amount,
  currency,
  source_id,
  type
from balance_transactions
order by day desc
limit 5

最も一般的な財務サマリーは、balance_transactions テーブルを、該当する情報が収録された他のテーブルと結合することで計算できます。Stripe のクエリテンプレートの一部 (日次残高、月次のサマリーと残高など) は、このテーブルを他のテーブルに結合することで機能します。

取引残高手数料の詳細

個々の取引残高に関する手数料情報は、balance_transaction_fee_details テーブルに含まれています。このテーブルを以下の方法で balance_transactions に結合すると、各取引残高の手数料情報を取得することができます。

次のクエリは、balance_transactions テーブルと balance_transaction_fee_details テーブルを結合します。返される各取引残高アイテムには、金額、手数料、適用される手数料の種類、および手数料の説明が含まれます。

select
  date_format(date_trunc('day', balance_transactions.created), '%m-%d-%Y') as day,
  balance_transactions.id,
  balance_transactions.amount,
  balance_transactions.fee,
  balance_transaction_fee_details.type
from balance_transactions
inner join balance_transaction_fee_details
  on balance_transaction_fee_details.balance_transaction_id=balance_transactions.id
order by day desc
limit 5

チャージ

charges テーブルには、Charge (支払い) オブジェクトに関するデータが含まれています。このテーブルは、会計や照合に使用するのではなく、支払い固有の情報に焦点を当てたクエリに使用します。また、追加の顧客データで会計報告諸表を補完します。たとえば、支払いカードの内訳テンプレートのクエリは、charges テーブルを使用して、顧客が使用したさまざまな種類のカードに関するレポートを作成します。

charges テーブルを多数の他のテーブルに結合し、クエリでより多くの情報を取得できます。

次の例では charges テーブルを使用して、失敗した支払いについてのレポートを作成し、カードブランド、および失敗のコードとメッセージを返します。

select
  date_format(date_trunc('day', created), '%m-%d-%Y') as day,
  id,
  card_brand,
  failure_code,
  failure_message
from charges
  where status = 'failed'
order by day desc
limit 5

顧客

customers テーブルには、Customer (顧客) オブジェクトに関するデータが収録されています (このテーブルは 支払いのテーブルグループには含まれません)。顧客を使用して支払いを作成している (保存されている支払い情報を使用するなど) 場合などに使用します。また、サブスクリプションを使用している場合にも利用できます。

次の例では、失敗した支払いのリストを、各顧客の ID とメールアドレスとともに取得します。

select
  date_format(date_trunc('day', charges.created), '%m-%d-%Y') as day,
  customers.id,
  customers.email,
  charges.id
from charges
inner join customers
on customers.id=charges.customer_id
where charges.status = 'failed'
order by day desc
limit 5

返金

支払いと返金は、API 内の個別のオブジェクトです。支払いが返金されると、Refund (返金) が作成されます。このデータは refunds テーブル内で利用でき、実行された返金に関する詳細情報を提供します。支払いに関するレポートと同様、ベストプラクティスは取引残高に関する情報から始めることです。その後、必要に応じて refunds テーブルを使用して追加情報を収集できます。

refunds テーブルを balance_transactions テーブルと charges テーブルに結合すると、返金データをさらに詳しく調べることができます。

次の例では、refunds.balance_transaction_id 列と balance_transactions.id 列を使用して、balance_transactions テーブルと refunds テーブルを結合します。返される各取引残高項目は返金であり、関連する支払い ID と金額が表示されます。特定の日付以降に作成された取引残高のみが返されます。

select
  date_format(date_trunc('day', balance_transactions.created), '%m-%d-%Y') as day,
  balance_transactions.source_id,
  refunds.charge_id,
  balance_transactions.amount
from balance_transactions
inner join refunds
on refunds.balance_transaction_id=balance_transactions.id
  where balance_transactions.type = 'refund'
order by day desc
limit 5

一部キャプチャーによる返金

オーソリとキャプチャーを使用し、承認された金額の一部のみをキャプチャすると、支払いと返金の両方が発生します。承認された請求は、全額の charge と関連する取引残高を作成します。部分的なキャプチャが完了すると、キャプチャされていない金額がリリースされ、partial_captureの reason フィールドと関連する取引残高とともに refund が作成されます。

たとえば、10 USD の支払いをオーソリして、7 USD しかキャプチャーしない場合は、10 USD の charge が作成されます。さらに、残りの 3 USD に対して partial_capture を理由とする refund が作成されます。

お客様のビジネスが支払いのオーソリとキャプチャーを実行している場合、顧客の返金率を審査するためのレポートを作成する際には、一部キャプチャーによる返金を考慮してください。考慮しない場合、オーソリとキャプチャーは不正確なアカウントの返金件数を表す可能性があります。支払い情報を取得するときに、返金の reason フィールドを使用して、一部キャプチャーによる返金を除外します。

select
  balance_transactions.id,
  balance_transactions.amount
from balance_transactions
inner join refunds
on refunds.id=balance_transactions.source_id
where reason != 'partial_capture'
limit 5

送金と入金

transfers テーブルには、Stripe 残高から銀行口座への入金に関するデータが収録されています。自動入金を使用していれば、このテーブルを使用して、各入金とその入金を構成する個々の支払い、返金、および調整を照合できます。

Connect プラットフォームの場合、このテーブルには、連結された Stripe アカウントへの売上送金に関するデータも含まれています。

手動で入金を行う場合、銀行口座に任意の額を入金できます。このため、特定の取引残高との照合ができなくなり、リクエストした銀行口座への入金額のみが反映されます。

次の例では、balance_transactions テーブルと transfers テーブルを結合します。支払いと返金のリスト、それらに関連する入金、および銀行口座への入金到着予定日が返されます。

select
  date_format(date_trunc('day', balance_transactions.created), '%m-%d-%Y') as bt_created,
  balance_transactions.source_id,
  balance_transactions.type,
  balance_transactions.net as net_amount,
  balance_transactions.automatic_transfer_id as transfer_id,
  date_format(date_trunc('day', transfers.date), '%m-%d-%Y') as transfer_date
from balance_transactions
inner join transfers
on balance_transactions.automatic_transfer_id=transfers.id
where balance_transactions.type = 'charge'
and balance_transactions.type != 'refund'
order by bt_created desc
limit 5

送金の差戻し

手動で作成した入金 (または Stripe の連結アカウントへの振込) は、まだ入金が実行されていなければ、アカウント内の利用可能残高に戻された売上を使用して差し戻すことができます。資金は、Transfer_reversal オブジェクトとして示され、transfer_reversals テーブルに記録されます。

振込の差戻しは、手動で作成された入金と振込にのみ適用されます。自動入金を差戻すことはできません。