# Financial Connections アカウントの残高にアクセスする

ユーザーの許可を得て口座の残高にアクセスする方法をご紹介します。

Financial Connections API を使用すると、[Financial Connections アカウント](https://docs.stripe.com/api/financial_connections/accounts.md)の最新の残高を取得できます。残高データは、ACH での資金不足による失敗のリスク軽減、リスク評価、財務管理ツールの構築など、さまざまな用途に利用できます。

## Before you begin

本番環境で balances にアクセスするには、Financial Connections の登録を完了している必要があります。[ダッシュボードの設定](https://dashboard.stripe.com/settings/financial-connections)に移動して登録状況を確認するか、登録プロセスを開始してください。Financial Connections のテストデータはいつでも利用できます。

## 顧客を作成する [Recommended] [Server-side]

ユーザーを表すメールアドレスと電話番号を含めて*顧客* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments)を作成し、その顧客を決済に関連付けることをお勧めします。`Customer` オブジェクトを関連付けることで、後で[以前に関連付けられた口座](https://docs.stripe.com/api/financial_connections/accounts/list.md)を一覧表示できます。`Customer` オブジェクトにメールアドレスと電話番号を入力すると、ユーザーがリピートの[Link](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses)ユーザーかどうかに応じて、Financial Connections がサインインまたはサインアップを簡素化し、認証フローを改善できます。

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d phone={{CUSTOMER_PHONE}}
```

## 口座の残高へのアクセスをリクエストする [サーバー側]

残高データにアクセスするには、口座を収集する必要があります。Financial Connections アカウントの収集方法について、詳細は[決済の受け付け](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md)、[Connect での入金の円滑化](https://docs.stripe.com/financial-connections/connect-payouts.md)、[データを利用するその他の商品の構築](https://docs.stripe.com/financial-connections/other-data-powered-products.md)など、ユースケースに最も適した導入ガイドをご覧ください。

口座を収集するときはアクセスする必要があるデータを [permissions](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions) パラメーターで指定します。ユーザーは[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)で、一連のリクエスト対象のデータ権限を表示できます。Financial Connections アカウントはさまざまな導入パスで収集できますが、パラメーターの指定方法は API によって若干異なります。

インテントを作成する前に、ダッシュボードで決済手段として[アメリカの銀行口座を有効化](https://dashboard.stripe.com/settings/payment_methods)してください。

#### Payment Intents

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=20000 \
  -d currency=usd \
  -d "customer={{CUSTOMER_ID}}" \
  -d "automatic_payment_methods[enabled]=true" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method"
```

#### Setup Intents

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "automatic_payment_methods[enabled]=true" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method"
```

#### Sessions

```curl
curl https://api.stripe.com/v1/financial_connections/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "account_holder[type]=customer" \
  -d "account_holder[customer]={{CUSTOMER_ID}}" \
  -d "permissions[]=balances"
```

#### Checkout

```curl
curl https://api.stripe.com/v1/checkout/sessions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method"
```

#### 請求書

```curl
curl https://api.stripe.com/v1/invoices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "customer={{CUSTOMER_ID}}" \
  -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=balances" \
  -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=payment_method"
```

#### サブスクリプション

```curl
curl https://api.stripe.com/v1/subscriptions \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=balances" \
  -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=payment_method"
```

特定の支払い API に対して動的な支払い方法を使用するときは、リクエストされた権限をダッシュボードで設定することもできます。[Financial Connections アカウントでその他の口座データにアクセスする](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md?dashboard-or-api=dashboard#access)方法をご覧ください。

## 残高更新を開始する [サーバー側]

Financial Connections データの取得はすべて非同期で行われます。残高の更新を開始して、完了を待ってから結果を取得します。残高の更新は、`prefetch` API パラメーターを使用するか、[Refresh API](https://docs.stripe.com/api/financial_connections/accounts/refresh.md) を使用して開始できます。

### 残高データをプリフェッチする

口座の収集「前」に、口座残高をプリフェッチするかどうかを指定します。これにより、[認証フロー](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow)でユーザーが自分の口座を連結するとすぐに更新プロセスが開始されます。関連付けられた口座すべての残高データが必要なときや、データを最短で受け取るようにするときは `prefetch` を設定します。この例としては、ACH 支払いの開始前に残高確認の実行を予定する場合が挙げられます。`prefetch` パラメーターは Financial Connections に対応するすべての API で使用できます。

```curl
curl https://api.stripe.com/v1/payment_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d amount=20000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true" \
  -d "payment_method_options[us_bank_account][financial_connections][prefetch][]=balances" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances"
```

### オンデマンド更新を開始する

[Refresh API](https://docs.stripe.com/api/financial_connections/accounts/refresh.md) を使用すると、口座の収集「後」にオンデマンドで残高の更新を開始し、特定の口座の残高情報を都合の良いときに取得できるため、判断を先送りできます。

Financial Connections アカウント ID を使用して更新を開始します。決済フローを使用して実装する場合は、[関連付けられている支払い方法](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#finding-the-financial-connections-account-id)でアカウント ID を見つけます。Financial Connections Session を使用するときは、[該当セッション](https://docs.stripe.com/financial-connections/other-data-powered-products.md?platform=web#collect-an-account)から ID を取得します。

```curl
curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}}/refresh \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "features[]=balance"
```

> 更新は非アクティブなアカウントでは実行できません。

### 残高更新の完了を待つ

Financial Connections アカウントの [balance_refresh](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-balance_refresh) フィールドは、残高の更新ステータスを表します。`balances` 権限をリクエストして更新を開始するまで、このフィールドは `null` になります。残高の更新を開始すると、ステータスは `pending` に移行し、完了すると `succeeded` または `failed` になります。残高更新の完了時に Stripe は [financial_connections.account.refreshed_balance](https://docs.stripe.com/api/events/types.md#event_types-financial_connections.account.refreshed_balance) イベントを送信します。更新が成功したことを確認するには、Webhook の処理中に `balance_refresh.status` フィールドを確認します。

残高の更新フロー (See full diagram at https://docs.stripe.com/financial-connections/balances)

```text
[balance_refresh: null] -- プリフェッチ --> [balance_refresh.status: pending]
[balance_refresh: null] -- Refresh API --> [balance_refresh.status: pending]
[balance_refresh.status: pending] -- 成功 --> [balance_refresh.status: succeeded]
[balance_refresh.status: pending] -- 失敗 --> [balance_refresh.status: failed]
[balance_refresh.status: succeeded] -- 送信される Webhook --> [financial_connections.account.refreshed_balance]
[balance_refresh.status: failed] -- 送信される Webhook --> [financial_connections.account.refreshed_balance]
```

残高の更新が完了すると、Stripe は [balance_refresh.next_refresh_available_at](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-balance_refresh-next_refresh_available_at) フィールドを使用して将来の更新の提供状況を設定します。新しい残高の更新を開始する前にこのフィールドを調べて、更新が現在利用可能かどうかを確認してください。値が `null` のとき (更新が保留中か口座が非アクティブの場合は常にこの値) または現在時刻が `next_refresh_available_at` タイムスタンプより前のときに更新しようとすると、更新は開始されません。

> まれですが、更新に失敗した場合は、プレビュー版の機能である更新ハッシュの `error` フィールドに、失敗の原因と推奨される次の手順が示されます。ご利用になりたい場合は、[メールでお問い合わせください](mailto:financial-connections-beta+refresh-error@stripe.com)。

## 口座の残高を取得する [サーバー側]

更新が正常に完了した後に、[financial_connections.account.refreshed_balance](https://docs.stripe.com/api/events/types.md#event_types-financial_connections.account.refreshed_balance) イベントの本文から、または API を使用して Financial Connections アカウントを取得します。

```curl
curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

更新が正常に完了すると、Account (口座) オブジェクトに残高データが組み込まれます。

```json
{
  "id": "fca_1Jbry3BAjqvGMUSxCDjFsrLU",
  "object": "financial_connections.account",
  "balance": {
    "as_of": 1651516592,
    "cash": {
      "available": {
        "usd": 6000
      }
    },
    "current": {
      "usd": 6000
    },
    "type": "cash"
  },
  "balance_refresh": {
    "last_attempted_at": 1651516582,
    "next_refresh_available_at": 1651516583,
    "status": "succeeded",
  },
  // ... other fields on the Financial Connections Account
}
```

#### 残高データの詳細

`balance` ハッシュは、金融機関から提供された残高それぞれのタイプを表します。

| 残高タイプ | 説明 |
| --- | --- |
| `current` | `current` 残高は、口座に転記済みの資金の金額です。この金額には、入金や送金、およびその他の保留金など、まだ口座に転記されていないイベントは反映されていません。プラスの金額は、口座所有者に支払われるべき金額を示します。マイナスの金額は、口座所有者が支払うべき金額を示します。 |
| `available` | balance オブジェクトは多態性があり、タイプは `cash` および `credit` になります。残高に `type: "cash"` が指定されている場合、`available` プロパティーが設定された `cash` サブジェクトが表示されます。このプロパティーは保留中の入出金金額を適用後の利用可能金額を示し、この金額は送金や入金に使用できます。 |
| `used` | balance オブジェクトには多態性があり、タイプは `cash` および `credit` になります。balance に `type: "credit"` が指定されている場合、`used` プロパティーが指定された `credit` サブオブジェクトが表示されます。このプロパティーは保留中の出金額が適用された後に使用された資金の金額を示します。クレジット残高の場合、`current` と `used` の金額には、現金残高の場合と同じ符号の規則が使用されます。プラスの金額は「口座所有者に」支払われるべき金額を表し、マイナスの金額は「口座所有者が」支払うべき金額を表します。ほとんどの場合、クレジット残高の金額はマイナスです。 |

利用可能な残高は、関連付けられている金融機関によって異なります。Stripe からアクセスできるすべての残高データが返されます。稀に、特に小規模な金融機関との取引の場合、Stripe が金融機関やあらゆる種類のパートナーから残高データを取得できないことがあります。このような場合は `balance` オブジェクトが `null` になります。口座の連結が切れている場合も balance オブジェクトが `null` になります。状況によっては `current` 残高のみが返されるか、最大 24 時間古い残高が返されます。データの対象については、サポート対象の[金融機関](https://docs.stripe.com/financial-connections/supported-institutions.md)のリストをご覧ください。

`cash` 残高タイプの場合、ACH ダイレクトデビットによる支払いの開始前に `available` サブオブジェクトを使用して、十分な資金があることを確認します。`available` 残高が null である場合は、`current` 残高を使用して、ACH ダイレクトデビットによる支払いの開始前に十分な残高があることを確認できますが、この金額には、入金や送金、およびその他の保留金など、まだ口座に転記されていないイベントが反映されていないことに注意してください。

残高の `as_of` フィールドは、金融機関がこの残高を計算した日時です。この日時は残高データの取得日時とは異なります。たとえば、1 日に 1 回しか残高データを更新しない金融機関もあれば、それよりも更新頻度が高い金融機関もあります。