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

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

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

はじめに

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

顧客を作成する
Recommended
Server-side

We recommend that you create a Customer with an email address to represent your user, that you then attach to your payment. Attaching a Customer object allows you to list previously linked accounts later. By providing an email address on the Customer object, Financial Connections can improve the authentication flow by simplifying sign-in or sign-up for your user, depending on whether they’re a returning Link user.

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

残高データにアクセスするには、口座を収集する必要があります。Financial Connections アカウントの収集方法について、詳細は決済の受け付け、Connect での入金の円滑化、データを利用するその他の商品の構築など、ユースケースに最も適した導入ガイドをご覧ください。

口座を収集するときはアクセスする必要があるデータを permissions パラメーターで指定します。ユーザーは認証フローで、一連のリクエスト対象のデータ権限を表示できます。Financial Connections アカウントはさまざまな導入パスで収集できますが、パラメーターの指定方法は API によって若干異なります。

特定の支払い API に対して動的な支払い方法を使用するときは、リクエストされた権限をダッシュボードで設定することもできます。Financial Connections アカウントでその他の口座データにアクセスする方法をご覧ください。

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

Financial Connections データの取得はすべて非同期で行われます。残高の更新を開始して、完了を待ってから結果を取得します。残高の更新は、prefetch API パラメーターを使用するか、Refresh API を使用して開始できます。

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

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

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

Refresh API を使用すると、口座の収集「後」にオンデマンドで残高の更新を開始し、特定の口座の残高情報を都合の良いときに取得できるため、判断を先送りできます。

Financial Connections アカウント ID を使用して更新を開始します。決済フローを使用して実装する場合は、関連付けられている支払い方法でアカウント ID を見つけます。Financial Connections Session を使用するときは、該当セッションから ID を取得します。

注

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

残高更新の完了を待つ

Financial Connections アカウントの balance_refresh フィールドは、残高の更新ステータスを表します。balances 権限をリクエストして更新を開始するまで、このフィールドは null になります。残高の更新を開始すると、ステータスは pending に移行し、完了すると succeeded または failed になります。残高更新の完了時に Stripe は financial_connections.account.refreshed_balance イベントを送信します。更新が成功したことを確認するには、Webhook の処理中に balance_refresh.status フィールドを確認します。

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

プライベートプレビュー

まれですが、更新に失敗した場合は、プレビュー版の機能である更新ハッシュの error フィールドに、失敗の原因と推奨される次の手順が示されます。ご利用になりたい場合は、メールでお問い合わせください。

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

更新が正常に完了した後に、financial_connections.account.refreshed_balance イベントの本文から、または API を使用して Financial Connections アカウントを取得します。

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

{
  "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 残高のみが返されます。データの対象については、サポート対象の金融機関のリストをご覧ください。

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

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

注