Treasury 金融口座を使用する
プラットフォームで Stripe Treasury を有効にすると、FinancialAccount
オブジェクトをプラットフォームアーキテクチャーに追加して、資金の効率的な保管、送金、受け取りを有効にすることができます。Treasury への API アクセスを獲得すると、Stripe は金融口座をプラットフォームアカウントに関連付けます。これにより、プラットフォームのそれぞれの Custom 連結アカウントに個々の金融口座を提供できるようになります。
注
Multiple Financial Accounts ベータ Multiple Financial Account ベータ機能を使用すると、1 つの Custom 連結アカウントに対して複数の金融口座を開設することができます。テスト環境でこの機能を利用して、待機リストに登録するには、treasury-support@stripe.com にご連絡ください。
各金融口座には、それが関連付けられているアカウントの残高とは別個の、明確な資金の残高があります。たとえば、プラットフォーム上の Custom 連結アカウントの所有者が、100 USD の連結アカウント残高と 200 USD の金融口座残高を持っているとします。この場合、連結アカウントの所有者は金融口座と連結アカウントの残高全体で、合計 300 USD を所有しています。この 2 つの残高は別々に維持されますが、API は、連結アカウントの残高から金融口座の残高に資金を移動できるようにします。
Stripe API では、FinancialAccount
オブジェクトは、資金移動の API リクエストの送金元と送金先として機能します。API を通じ、プラットフォーム上の金融アカウントに追加機能を提供する Features
をリクエストし、FinancialAccounts
に割り当てます。 たとえば、特定の金融アカウントの支払いカード機能を有効にするには、FinancialAccount
ID を使用して、card_issuing
機能の API リクエストを送信します。Feature
オブジェクトの詳細については、金融アカウントの機能をご覧ください。各 Feature
に必要な連結アカウントのケイパビリティを確認するには、同ガイド内の使用可能な機能セクションをご覧ください。
Treasury の組み込みの金融口座を本番環境で作成する前に、まず、テスト環境でテスト用の金融口座を作成することをお勧めします。テスト環境の金融口座では、実際の資金の受け取りと送金を行うことはできず、本番環境では使用できません。また、実際の金融番号と口座番号の情報を使用して本番環境の口座を生成することはありませんが、その他の構成や機能は本番環境と同じです。
FinancialAccount を作成する
POST /v1/treasury/financial_accounts
を使用して FinancialAccounts
を作成します。コールの Stripe-Account
ヘッダーの値として連結アカウントの ID を含め、その FinancialAccount
を連結アカウントと関連付けます。現時点では、各連結アカウントが持つことができる FinancialAccount
は 1 つのみです。
注
Multiple Financial Accounts ベータ Stripe-Account
ヘッダーの値として同じ連結アカウントの ID を提供すると、連結アカウントに複数の金融口座を関連付けることができます。デフォルトでは、1 つの連結アカウントに関連付けできる金融口座は最大 10 件です (閉鎖された 金融口座はこの上限に含まれません)。アカウントの最大値を引き上げる必要がある場合は、treasury-support@stripe.com にご連絡ください。
以下の JSON は、FinancialAccount
オブジェクトの構造を定義します。
通常、アカウントを作成するための API リクエストを行う際に金融口座の機能もリクエストします。リクエストする Features
にかかわらず、連結アカウントでは、treasury
ケイパビリティが有効化されている必要があります。連結アカウントにこのケイパビリティがあるかどうか分からない場合には、GET /v1/accounts/{{CONNECTED_ACCOUNT_ID}}
を使用して確認します。アカウントのcapabilities
ハッシュには、active
の treasury
値が必要です。
… "capabilities": { "card_issuing": "active", "card_payments": "active", "transfers": "active", "treasury": "active", "us_bank_account_ach_payments": "active" }, …
金融口座の残高に関連付けられたカードを発行するには、プラットフォームの連結アカウントで Issuing (card_issuing
) ケイパビリティが有効になっている必要があります。金融口座の card_issuing
機能をリクエストするには、連結アカウントにこのケイパビリティが存在する必要があります。連結アカウントにこのケイパビリティがない場合は、card_issuing
機能をリクエストして FinancialAccount
を作成しようとするとエラーが発生します。
注
Multiple Financial Account ベータ FinancialAccount
オブジェクトの nickname
フィールドを設定して、金融口座にカスタムの名前を使用することができます。ニックネームを使用して一意の識別子を作成できるため、1 つの連結アカウントで複数の金融口座を処理する場合に便利です。ニックネームを有効にするには、次の要件があります。
- 特定の連結アカウントの各金融口座で一意である
- 空白以外の文字列であること
- 250 文字未満
アカウント作成時にニックネームを入力しない場合、ニックネームフィールドは空のため null
を返します。FinancialAccount
の作成後に、ニックネームを更新できます。
以下のリクエストは、Stripe-Account
ヘッダーに指定された ID を持つ、連結アカウントに割り当てられた金融口座を作成します。
レスポンスは、金融口座の作成を確認する FinancialAccount
オブジェクトです。
{ "object": "treasury.financial_account", "created": 1612927106, "id": "fa_123", "country": "US", "supported_currencies": ["usd"], "active_features": [ "card_issuing", ], // Features that require activation enter a pending state before activating "pending_features": [ "deposit_insurance", "financial_addresses.aba", "inbound_transfers.ach", "intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire", "outbound_transfers.ach", "outbound_transfers.us_domestic_wire" ], "restricted_features": [], // A FinancialAddress is not added until the financial_addresses.aba feature has been activated "financial_addresses": [], "livemode": true, "status": "open", ... }
FinancialAccount を更新する
POST /v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}
を使用して、関連付けられた ID の FinancialAccount
を更新します。Stripe-Account
ヘッダー値として連結アカウントの ID を含めます。以下の例は、 FinancialAccount のメタデータを更新します。
FinancialAccount と口座番号を取得する
GET /v1/treasury/financial_accounts/{{FINANCIALACCOUNT_ID}}
を使用し、関連付けられた ID の FinancialAccount
を取得します。連結アカウントの ID を、Stripe-Account
ヘッダー値として含めます。
デフォルトでは、金融口座の口座番号はレスポンスに含まれていません。口座番号を取得するには、expand
配列に financial_addresses.aba.account_number
フィールドを含めます。
成功すると、レスポンスで、FinancialAccount
オブジェクトが返されます。expand
配列が含まれているかどうかに応じて、口座番号が示される場合と示されない場合があります。
expand
パラメーターの詳細については、レスポンスの拡張をご覧ください。
機能のサマリー
FinancialAccount
オブジェクトでは、すべての Features
の状態のサマリーが active_features
、pending_features
、restricted_features
の 3 つの配列に格納されます。
{ "object": "treasury.financial_account", "id": "fa_987", "status": "open", ... "active_features": ["card_issuing"], "pending_features": ["financial_addresses.aba"], "restricted_features": ["outbound_transfers.ach"], }
これらの配列は、以下を確認するのに便利です。
- アクティブではない機能 (
pending_features
またはrestricted_features
が空ではない)。 - アクティブな機能 (
active_features
に特定の機能が含まれている)。 - アクションが必要な制限付きの機能 (
restricted_features
が空ではない)。
詳細は、金融口座の機能をご覧ください。
FinancialAccount を閉鎖する
以下の条件を満たす場合には、金融口座を永久に閉鎖することができます。
- 残高がゼロです。
- 保留中のインバウンド送金はありません。
- 関連付けられたすべての Issuing カードがキャンセル済みです。
警告
閉鎖後に金融口座を再び開くことはできません。
金融口座を閉鎖するには、treasury-support@stripe.com に連絡して、閉鎖する FinancialAccount
ID と閉鎖の理由をお知らせください。Treasury コンプライアンスガイドラインに記載されているように、口座閉鎖についてユーザーに通知する必要があります。
金融口座の閉鎖は、Transactions
などの関連オブジェクトのデータ保管に影響を及ぼしません。
連結アカウントに関連付けられている金融口座を以前に閉鎖した場合、その連結アカウント用に新しい金融口座を開設することはできません。新しい金融口座を作成するには、新しい連結アカウントを開設する必要があります。
注
Multiple Financial Account ベータ Multiple Financial Account ベータ機能を使用すると、金融口座を閉鎖してから、新しい連結アカウントを開設することなく、同じ連結アカウントに関連付けられた新しい金融口座を開設することができます。
API を使用した FinancialAccount の閉鎖 ベータ
ベータプログラムへのアクセスを取得したら、POST/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close
を使用し、関連付けられた ID の金融口座を閉鎖します。ヘッダー値として、関連付けられた連結アカウントの ID を含めます。
curl https://api.stripe.com/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close \ -u
: \ -X "POST" \ -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"sk_test_4eC39HqLyjWDarjtT1zdp7dc
レスポンスは、アクションを確認する、 status
が closed
の FinancialAccount
オブジェクトです。
{ "id": "{{FINANCIAL_ACCOUNT_ID}}", "object": "treasury.financial_account", "status": "closed", "status_details": { "closed": { "reasons": ["closed_by_platform"] } }, "active_features": [], "pending_features": [], "restricted_features": ["financial_addresses.aba"], ... }
閉鎖された口座の取引を処理する
稀に、金融口座は、閉鎖された口座に対するクレジットやデビットを受け取ることがあります。閉鎖された口座の場合、Stripe は自動的に返金できません。口座閉鎖後に発生したマイナス残高の責任は、プラットフォームの所有者が負うことになります。売り手やサービスプロバイダーに支払うべき残金を返還し、閉鎖された口座のマイナス残高を修正できるよう Stripe サポートが協力します。
Webhook
アカウント登録要件を満たす前に金融口座を作成することができます。この場合、金融口座は非同期に開設され、その後 treasury.financial_account.features_status_updated
Webhook がトリガーされます。この Webhook では、アカウント登録要件が満たされていないため、制限されたままになっている機能の最新状態を確認することができます。
account.updated
- 新しい機能をリクエストすると、要件ハッシュが変更され一部の新しいフィールドが
pending_verification
になったことを通知する、account.updated
Webhook がプラットフォームで受信されることがあります。
- 新しい機能をリクエストすると、要件ハッシュが変更され一部の新しいフィールドが
treasury.financial_account.created
- FinancialAccount が新規作成されるたびにトリガーされます。
treasury.financial_account.closed
- 最上位の FinancialAccount が closed (閉鎖済み) に変わるったことを通知します。
treasury.financial_account.features_status_updated
- 1 つ以上の機能のステータスが変わったことを示します。これを反映して、
active_features
、pending_features
、またはrestricted_features
の配列に変更が加えられます。
- 1 つ以上の機能のステータスが変わったことを示します。これを反映して、