残高と取引の使用

金融口座には、それが関連付けられているアカウント (プラットフォームアカウントまたは連結アカウント) の残高とは別に、独自の残高があります。Balance オブジェクトは、金融口座にある資金額とその利用可能な状態を記録します。Transaction オブジェクトと TransactionEntry オブジェクトは、残高に対して資金の引き落とし、または入金を行います。

残高

金融口座には、資金の残高があります。ただし、金融口座からの資金の出入りに影響する保留中の取引が含まれる可能性があるため、残高の合計のすべてを常に使用できるわけではありません。金融口座の残高には、資金の可用性を定義する 3 つのプロパティが含まれます。

• cash: ユーザーがすぐに支出できる資金。
• inbound_pending: まだ支出可能になっていないものの、後で利用できるようになる資金。inbound_pending プロパティは、将来の機能のためにリザーブされており、値は常に 0 です。
• outbound_pending: アカウントにある資金のうち、保留中のアウトバウンドフロー用に留保されているため支出に使用できない金額。

GET /v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}} を使用し、関連付けられた ID の金融口座の残高詳細を取得します。その金融口座が連結アカウントの 1 つに関連付けられている場合には、Stripe-Account ヘッダーを指定します。その金融口座がプラットフォームアカウントに関連付けられている場合には、Stripe-Account ヘッダーを含めないでください。

curl https://api.stripe.com/v1/treasury/financial_accounts/
{{FINANCIAL_ACCOUNT_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

成功すると、レスポンスとして、資金とその利用可能状況の詳細を示す balance ハッシュが含まれた FinancialAccount オブジェクトが返されます。

{
  "object": "treasury.financial_account",
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  ...
  "balance": {
    // $90 is currently available for use,
    // with an additional $10 held in the outbound_pending sub-balance
    "cash": {"usd": 9000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  }
}

マイナス残高とオーバードラフト

連結アカウントの残高がマイナスの場合 (たとえば、金融口座が差戻しされる ACH クレジットを受け取った場合)、それを 0 USD に戻す責任があります。マイナスの状態が 180 日間続くと、Stripe はプラットフォームから引き落としを行います。個々の残高または合計残高が Stripe のリスク上限を超えた場合にも、ご連絡いたします。

連結アカウントをモニタリングして、マイナス残高の資金を取得することをお勧めします。インバウンド送金または Stripe入金を使用して、金融口座に資金をトップアップできます。連結アカウントの残高を定期的に監視し、速やかに連絡してください。

金融口座がマイナスの状態が 180 日間続くと、Stripe はプラットフォームの金融口座から資金を引き落とし、メールを事前に送信します。残高不足により送金が失敗した場合、Stripe はお客様に連絡し次の手順をご案内します。

取引

残高に対する変更のすべてに、それに対応する Transaction (取引) オブジェクトがあり、これは資金移動を詳細に示します。取引は 1 つの残高にのみ影響し、単一通貨です (現在、Stripe Treasury は USD にのみ対応しています)。

各取引は、OutboundTransfer、ReceivedCredit、または ReceivedDebit など、残高に影響する資金移動オブジェクトを指します。

取引のステートマシン

使用可能な Transaction エンドポイントを使用すると、特定の取引を取得でき、金融口座に影響している取引をリストまたはフィルタリングできます。取引に使用できる Webhook はありませんが、関連する資金移動オブジェクト (OutboundPayments など) には Webhook を使用できます。

取引を取得する

GET/v1/treasury/transactions/{{TRANSACTION_ID}} を使用して、関連付けられた ID の取引を取得します。

curl https://api.stripe.com/v1/treasury/transactions/txn_123 \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

成功すると、レスポンスは Transaction オブジェクトを返します。

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{Timestamp}}",
  "livemode": false,
  // The FinancialAccount this Transaction impacts
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The flow responsible for this Transaction. Each Transaction is created
  // synchronously (that is, in the same API request for initiated objects) with
  // its flow.

取引をリストする

GET /v1/treasury/transactions を使用して、金融口座の取引をリストします。本文で必須の financial_account パラメーターを、取引を取得する金融口座 ID の値に設定します。返された結果をフィルタリングするには、追加のパラメーターを含めます。

リストパラメーターの標準セットに加え、以下の方法で取引を絞り込むことができます。

• status
• flow
• created か posted_at のいずれか (両方ではなく)

{
  // Standard list parameters
  limit, starting_after, ending_before,
  // Filter by FinancialAccount, required
  financial_account: "{{FINANCIAL_ACCOUNT_ID}}"
  // Filter by status
  status: "open" | "posted" | "void",
  // Filter by flow
  flow: "{{FLOW_OBJECT_ID}}",
  // Order the results by the created or posted_at timestamps, default is `created`.
  // For order_by=posted_at, setting status='posted' is required
  order_by: "created" | "posted_at",
  // created can only be specified with order_by = 'created'
  created: {gt, gte, lt, lte},
  status_transitions: {
    // status_transitions.posted_at can only be specified with order_by = 'posted_at' and status = 'posted'
    posted_at: {gt, gte, lt, lte}
  }
}

次のリクエストは、金融口座で作成された、status が posted の直近 3 つの取引を取得します。

curl -G https://api.stripe.com/v1/treasury/transactions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d limit=3 \
  -d status=posted \
  -d order_by=created

Webhook

取引を開始するさまざまな資金移動には、それぞれの Webhook があるため、取引のための Webhook はありません。

取引項目

TransactionEntry (取引項目) オブジェクトは、金融口座の残高に影響を与える資金移動において最も細かなビューです。1 つの資金の流れは、複数の個別の資金移動から構成され、それぞれが取引で表されます。取引は、複数の取引項目を集約したものです。たとえば、T の時点で 10 USD の アウトバウンド支払いを開始すると、資金が cash サブ残高から outbound_pending サブ残高に移動します。以下の Transaction オブジェクトレスポンスは、この初期のイベントを示したものです。

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "open",
  "amount": -1000,
  "currency": "usd",

T+1 の時点でアウトバウンド支払いが転記されると、その資金は outbound_pending から差し引かれ、取引に新しい取引項目が追加されます。次の Transaction レスポンスは、この経過を示したものです。

{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "posted",
  "amount": -1000,
  "currency": "usd",

前述のレスポンスに示されるように、1 つの取引には複数の取引項目が含まれることがあります。利用可能な TransactionEntry エンドポイントを使用すると、特定の取引項目を取得でき、それらを特定の取引についてリストまたはフィルタリングできます。

void ステータスの Transaction には、新しい取引項目が追加されません。posted ステータスの Transaction で、すべての balance_impact が cash サブ残高に対するものである場合にも、新しい取引項目は追加されません。

取引項目を取得する

GET /v1/treasury/transaction_entries/{{TRANSACTIONENTRY_ID}} を使用して、関連付けられた ID の取引項目の詳細を取得します。

curl https://api.stripe.com/v1/treasury/transaction_entries/{{TRANSACTION_ENTRY_ID}} \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

成功すると、以下のフォームを持つ TransactionEntry オブジェクトがレスポインスで返されます。

{
  "id": "{{TRANSACTION_ENTRY_ID}}",
  "object": "treasury.transaction_entry",
  "created": "{{Timestamp}}",
  "livemode": false,
  // The FinancialAccount this transaction entry impacts.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The transaction that this transaction entry belongs to.
  "transaction": "{{TRANSACTION_ID}}",
  // The flow responsible for this transaction entry.

TransactionEntries をリストする

GET /v1/treasury/transaction_entries を使用して、金融口座の取引項目をリストします。本文で必須の financial_account パラメーターを、取引項目を取得する金融口座 ID の値に設定します。リストをフィルタリングするには、追加のパラメーターを含めます。

リストパラメーターの標準セットに加え、以下の方法で取引項目を絞り込むことができます。

• transaction
• created か effective_at のいずれか (両方ではなく)

{
  // Standard list parameters
  limit, starting_after, ending_before,
  // Filter by FinancialAccount, required
  financial_account: "fa_123"
  // Filter by transaction
  transaction: 'trxn_123',
  // Order the results by the created or effective_at timestamps, default is `created`.
  order_by: "created" | "effective_at",
  // created can only be specified with order_by = 'created'
  created: {gt, gte, lt, lte},
  // effective_at can only be specified with order_by = 'effective_at'
  effective_at: {gt, gte, lt, lte},
}

以下のリクエストは、{{Timestamp}} 以前に作成された取引項目を取得し、 created 日の順に並べます。

curl -G https://api.stripe.com/v1/treasury/transaction_entries \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
{{FINANCIAL_ACCOUNT_ID}} \
  -d order_by=created \
  -d "created[lt]"=1234567890

Webhook

取引項目を開始するさまざまな資金移動には、それぞれの Webhook があるため、取引項目のための Webhook はありません。