# 残高と取引の使用

金融口座の残高と取引が口座に与える影響について学びます。

[金融口座](https://docs.stripe.com/financial-accounts/connect/account-management/financial-accounts.md) は、それらが接続されているアカウント (プラットフォームアカウントまたは連結アカウント) の残高とは別に、独自の残高を持ちます。`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
curl https://api.stripe.com/v1/treasury/financial_accounts/{{TREASURYFINANCIALACCOUNT_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}"
```

成功すると、レスポンスとして、資金とその利用可能状況の詳細を示す `balance` ハッシュが含まれた [FinancialAccount](https://docs.stripe.com/api/treasury/financial_accounts.md) オブジェクトが返されます。

```json
{
  "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 に戻す必要があります。連結アカウントの金融口座の残高がマイナスになると、Stripe は直ちに貴社プラットフォームの[連結リザーブ残高](https://docs.stripe.com/connect/account-balances.md#understanding-connected-reserve-balances) (プラットフォームの[支払い残高](https://docs.stripe.com/payments/balances.md#payments-balance)から資金を供給) にマイナスと同額をリザーブします。このリザーブは、マイナスの金額が減ると自動的にリリースされます。個々のアカウントの残高または複数アカウントの残高合計が Stripe のリスク限度額を超えた場合、Stripe からお客様にご連絡します。

連結アカウントを監視し、マイナス残高の資金を回収することをお勧めします。[Inbound Transfers](https://docs.stripe.com/financial-accounts/connect/moving-money/into/inbound-transfers.md) または [Stripe Payouts](https://docs.stripe.com/financial-accounts/connect/moving-money/payouts.md) を利用して、金融口座に資金をトップアップすることができます。連結アカウントの残高を定期的に監視し、速やかにご連絡ください。

金融口座のマイナス状態が 180 日間続くと、Stripe はプラットフォームのリザーブから資金を移動させてマイナス残高を補填し、金融口座の残高をゼロに戻します。

## 取引

残高に対するすべての変更には、対応する [Transaction](https://docs.stripe.com/api/treasury/transactions.md) オブジェクトがあり、資金の動きの詳細が表示されます。取引は 1 つの残高にのみ影響し、1 つの通貨でのみ行われます (現在、プラットフォーム向け金融口座は USD のみに対応しています)。

各取引は、[OutboundTransfer](https://docs.stripe.com/api/treasury/outbound_transfers.md)、[ReceivedCredit](https://docs.stripe.com/api/treasury/received_credits.md)、または [ReceivedDebit](https://docs.stripe.com/api/treasury/received_debits.md) など、残高に影響する資金移動オブジェクトを指します。

### 取引のステートマシン

| ステータス    | 適用される状態 | 説明                                                                                   | 移行                  |
| -------- | ------- | ------------------------------------------------------------------------------------ | ------------------- |
| `open`   | 初期状態    | これはすべての取引の初期状態です。取引によってサブ残高の金額は更新されますが、現在の残高は取引が記帳されるまで影響を受けません。                     | `posted` または `void` |
| `posted` | 最終状態    | 資金はアカウントから正常に入金/出金されました。現在の残高に反映されています。                                              | 該当なし                |
| `void`   | 最終状態    | 取引が残高に影響しませんでした。たとえば、アウトバウンド支払いが開始された後で、アカウントから出金される前にキャンセルされた場合に、取引がこの状態になることがあります。 | 該当なし                |

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

## 取引を取得する

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

```curl
curl https://api.stripe.com/v1/treasury/transactions/txn_123 \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}"
```

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

#### JSON (コメント付き)

```json
{
  "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.
  "flow": "{{FLOW_OBJECT_ID}}",
  "flow_type": "inbound_transfer" |
             "outbound_payment" |
             "outbound_transfer" |
             "received_credit" |
             "received_debit" |
             "received_hold" |
             "issuing_dispute" |
             "credit_reversal" |
             "debit_reversal" |
             "other"
  "flow_details": null, // Includable, see user_expandable polymorphic object
  // Transaction state machine: open → posted | void
  // Transactions transition to posted when the amount is non-zero.
  // Transactions transition to void when the amount is zero AND the
  // sub-balance amounts are also zero.
  // Transactions are immutable once (posted && inbound_pending = 0) || void
  "status": "open" | "posted" | "void",
  // posted_at: When status changed from open -> posted
  // void_at: When status changed from open -> void
  // At most one of these may be set, because both posted and
  // void are terminal
  "status_transitions": {
    "posted_at": "{{?Timestamp}}",
    "voided_at": "{{?Timestamp}}"
  },
  // Transactions impact a single currency.
  "currency": "usd",
  // When status:
  //   open: This describes the projected change to the current balance.
  //         It can still change
  //   posted: The actual change to the current balance.
  //         Can no longer change
  //   void: Always 0 (the actual change to the current balance).
  //         Can no longer change
  "amount": 10000,
  "balance_impact": {
    "cash": 0,
    "inbound_pending": 10000,
    "outbound_pending": 0
  },
  // Freeform en-US string that describes this Transaction
  "description": "check deposit",
  "treasury": {
    // Set when the transaction transitions to `posted`.
    // The `financial_account.account.balance` amount as of `posted_at`
    // in `currency`.
    //
    // [DEPRECATION WARNING]: this field will be removed in the future.
    // Please avoid using it in new integrations.
    "current_balance_amount": "{{?Integer}}",
  },
  "entries": { // includable
    "object": "list",
    "data": [
      {
        "id": "{{TRANSACTION_ENTRY_ID}}",
        "object": "treasury.transaction_entry",
        ...
      }
    ],
    "has_more": false,
    "url": "/v1/treasury/transaction_entries?financial_account={{FINANCIAL_ACCOUNT_ID}}&transaction={{TRANSACTION_ID}}",
  }
}
```

### 取引をリストする

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

[リストパラメーターの標準セット](https://docs.stripe.com/api/pagination.md)に加え、以下の方法で取引を絞り込むことができます。

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

```json
{
  // 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
curl -G https://api.stripe.com/v1/treasury/transactions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d "financial_account={{TREASURYFINANCIALACCOUNT_ID}}" \
  -d limit=3 \
  -d status=posted \
  -d order_by=created
```

### Webhook

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

## 取引項目

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

```json
{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "open",
  "amount": -1000,
  "currency": "usd",
  "balance_impact": {
    "cash": -1000,
    "inbound_pending": 0,
    "outbound_pending": 1000,
  },
  "entries": {
    "data": [
      {
        "id": "{{TRANSACTION_ENTRY_ID}}",
        "object": "treasury.transaction_entry",
        ...
        "created": "{{T}}",
        "effective_at": "{{T}}",
        "currency": "usd",
        "balance_impact": {
          "cash": -1000,
          "inbound_pending": 0,
          "outbound_pending": 1000,
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/treasury/transaction_entries?financial_account=fa_123&transaction=trxn_123",
  }
}
```

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

```json
{
  "id": "{{TRANSACTION_ID}}",
  "object": "treasury.transaction",
  "created": "{{T}}",
  ...
  "flow": "{{OUTBOUND_PAYMENT_ID}}",
  "flow_type": "outbound_payment",
  "status": "posted",
  "amount": -1000,
  "currency": "usd",
  "balance_impact": {
    "cash": -1000,
    "inbound_pending": 0,
    "outbound_pending": 0,
  },
  "entries": {
    "data": [
      {
        "id": "{{TRANSACTION_ENTRY_ID}}",
        "object": "treasury.transaction_entry",
        ...
        "created": "{{T+1}}",
        "effective_at": "{{T+1}}",
        "currency": "usd",
        "balance_impact": {
          "cash": 0,
          "inbound_pending": 0,
          "outbound_pending": -1000,
        }
      },
      {
        "id": "{{TRANSACTION_ENTRY_ID}}",
        "object": "treasury.transaction_entry",
        ...
        "created": "{{T}}",
        "effective_at": "{{T}}",
        "currency": "usd",
        "balance_impact": {
          "cash": -1000,
          "inbound_pending": 0,
          "outbound_pending": 1000,
        }
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/treasury/transaction_entries?financial_account={{FINANCIAL_ACCOUNT_ID}}&transaction={{TRANSACTION_ID}}",
  }
}
```

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

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

### 取引項目を取得する

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

```curl
curl https://api.stripe.com/v1/treasury/transaction_entries/{{TRANSACTION_ENTRY_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}"
```

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

```json
{
  "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.
  "flow": "{{FLOW_OBJECT_ID}}",
  "flow_type": "inbound_transfer" |
             "outbound_payment" |
             "outbound_transfer" |
             "received_credit" |
             "received_debit" |
             "received_hold" |
             "issuing_dispute" |
             "credit_reversal" |
             "debit_reversal" |
             "other",
  "flow_details": null, // Includable, see user_expandable polymorphic object
  // type describes the specific money movement that generated the transaction entry.
  "type": "outbound_payment" |
        "outbound_payment_cancellation" |
        "outbound_payment_failure" |
        "outbound_payment_posting" |
        "outbound_payment_return" |
        "outbound_transfer" |
        "outbound_transfer_cancellation" |
        "outbound_transfer_failure" |
        "outbound_transfer_posting" |
        "outbound_transfer_return" |
        "received_credit" |
        "received_debit" |
        "received_hold" |
        "received_hold_release" |
        "credit_reversal" |
        "credit_reversal_posting" |
        "debit_reversal" |
        "stripe_fee" |
        "inbound_transfer" |
        "other",
  // effective_at describes when the transaction entry impacted, or will impact, the FinancialAccount's balance.
  "effective_at": "{{Timestamp}}",
  // `effective` if `effective`_at` is in the past, otherwise `scheduled`.`
  "status": "effective" | "scheduled",
  // Transaction entries impact a single currency.
  "currency": "usd",
  // balance_impact describes the change to each sub-balance for this transaction entry.
  "balance_impact": {
    "cash": 0,
    "inbound_pending": 10000,
    "outbound_pending": 0
  }
}
```

### TransactionEntries をリストする

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

[リストパラメーターの標準セット](https://docs.stripe.com/api/pagination.md)に加え、以下の方法で取引項目を絞り込むことができます。

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

```json
{
  // 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
curl -G https://api.stripe.com/v1/treasury/transaction_entries \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Account: {{CONNECTEDACCOUNT_ID}}" \
  -d "financial_account={{TREASURYFINANCIALACCOUNT_ID}}" \
  -d order_by=created \
  -d "created[lt]=1234567890"
```

### Webhook

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