金融口座の使用

金融口座を使用して、資金の保管、送金、受け取りを行います。

プラットフォーム向け金融口座への API アクセス権を取得すると、Stripe はプラットフォームアカウントに金融口座をアタッチし、プラットフォーム上で対象となる連結アカウントに金融口座をプロビジョニングできるようになります。各金融口座は、関連付けられたアカウントの残高とは別に、独自の残高を持ちます。例えば、あなたのプラットフォーム上の連結アカウントの所有者は、100 USD 連結アカウント残高と 200 USD 金融口座残高を持っているかもしれません。このシナリオでは、連結アカウントの所有者は、金融口座と連結アカウントの残高の間に 300 USD の合計が広がっています。これら 2 つの残高は別々のままですが、API は連結アカウント残高から金融口座残高に資金を移動する機能を提供します。

Stripe API では、FinancialAccount オブジェクトが資金移動 API リクエストのソースおよび宛先として機能します。FinancialAccounts に割り当てる Features を API でリクエストします。例えば、特定の金融口座で決済カード機能を有効にするには、FinancialAccount ID で card_issuing 機能の API リクエストを送信します。Feature オブジェクトの詳細については、金融口座機能を参照してください。各 Feature に必要な連結アカウントケイパビリティを確認するには、そのガイド内の利用可能な機能セクションを参照してください。

プラットフォーム向け金融口座の導入のために本番環境で金融口座を作成する前に、まずサンドボックス環境でテスト金融口座を作成することをお勧めします。テスト金融口座は実際の資金を送受信できず、本番環境では使用できず、実際の金融番号とアカウント情報を持つ本番アカウントを生成しませんが、その他の構成と機能は同じです。

FinancialAccount を作成する

POST /v1/treasury/financial_accounts を使用して FinancialAccounts を作成します。コールの Stripe-Account ヘッダーの値として連結アカウントの ID を含め、その FinancialAccount を連結アカウントと関連付けます。

プラットフォームアカウントと連結アカウントには、複数の金融口座を関連付けることができます。連結アカウント ID を Stripe-Account ヘッダーの値として指定することで、連結アカウントに別の金融口座を作成できます。1 つの連結アカウントに最大 3 口の金融口座を関連付けることができます (閉鎖された金融口座は上限にカウントされません)。プラットフォームアカウントに関連付けられる金融口座の数にも同じ制限が適用されます。アカウントのしきい値を引き上げる必要がある場合は、treasury-support@stripe.com にお問い合わせください。

以下の JSON は、FinancialAccount オブジェクトの構造を定義します。

言語を選択JSON (コメント付き)
JSON
 No results
{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "fa_123",
  "country": "US",
  "supported_currencies": ["usd"],
  // Arrays of active, pending and restricted features summarize the status of all requested features
  "active_features": ["financial_addresses.aba", "deposit_insurance"],
  "pending_features": ["inbound_transfers.ach"],
  "restricted_features": ["intra_stripe_flows", "outbound_payments.ach", "outbound_payments.us_domestic_wire"],
  "balance": {
    "cash": {"usd": 9000},
    "inbound_pending": {"usd": 0},
    "outbound_pending": {"usd": 1000}
  },
  // The FinancialAccount gains a FinancialAddress once the `financial_addresses.aba` feature is active. For more information, see "Activating features"
  "financial_addresses": [
    {
      "type": "aba",
      "supported_networks": ["ach", "domestic_wire_us"],
      "aba": {
        "account_number_last4": "7890",
        // Use the expand[] parameter to view the `account_number` field hidden by default
        "account_number": "1234567890",
        "routing_number": "000000001",
        "bank_name": "Goldman Sachs"
      }
    }
  ],
  "livemode": true,
  // Financial accounts begin in the "open" state, but can be closed
  // `status_details.closed` is populated once a financial account is closed
  "status": "open",
  "status_details": {
    "closed": {
      // List of one or more reasons why the FinancialAccount was closed:
      // - account_rejected
      // - closed_by_platform
      // - other
      "reasons": [],
    }
  },
  // User-defined metadata
  "metadata": {},
  "nickname": {},
  // Restrictions that the platform can apply to the FinancialAccount
  "platform_restrictions": {
    "inbound_flows": "unrestricted",
    "outbound_flows": "restricted"
  },
}

通常、API リクエストでアカウントを作成する際に、金融口座機能もリクエストします。Features にかかわらず、連結アカウントは treasury ケイパビリティを有効にしている必要があります。連結アカウントにケイパビリティがあるかどうか不明な場合は、GET /v1/accounts/{{CONNECTED_ACCOUNT_ID}} を使用して確認してください。アカウントの capabilities ハッシュには treasury の値が active である必要があります。

…
  "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 を作成しようとするとエラーが発生します。

FinancialAccount オブジェクトの nickname フィールドを設定して、金融口座のカスタム名を指定します。ニックネームを使用して識別子を作成できるため、1 つの連結アカウントで複数の金融口座を操作する場合に便利です。有効なニックネームは、以下の条件を満たす必要があります。

空白以外の文字列であること
250 文字未満

アカウント作成時にニックネームを入力しなかった場合、ニックネームフィールドは空になり、null を返します。FinancialAccount を作成した後、更新でニックネームを更新することができます。

以下のリクエストは、Stripe-Account ヘッダーに指定された ID を持つ、連結アカウントに割り当てられた金融口座を作成します。

レスポンスは、金融口座の作成を確認する FinancialAccount オブジェクトです。

{
  "object": "treasury.financial_account",
  "created": 1612927106,
  "id": "{{FINANCIAL_ACCOUNT_ID}}",
  "country": "US",
  "supported_currencies": ["usd"],
  "active_features": [
    "card_issuing",
  ],
  // Features that require activation enter a pending state before activating

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 配列が含まれているかどうかに応じて、口座番号が示される場合と示されない場合があります。

言語を選択拡張された口座を示すレスポンス
デフォルトのレスポンス
 No results
{
  "id": {{FINANCIAL_ACCOUNT_ID}},
  ...
  "financial_addresses": [
    {
      "aba": {
        "account_holder_name": "jenny",
        "account_number": "4242424242420239",
        "account_number_last4": "0239",
        "bank_name": "Stripe Test Bank",
        "routing_number": "000000001"
      },
      ...
    }
  ],
  ...
}

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 カードがキャンセル済みです。
アカウント残高がゼロで、過去 75 日間にアカウントの取引がありません。または、別の金融口座または検証済み外部アカウントを指定し、転送して入出金を処理することもできます。

警告

閉鎖後に金融口座を再び開くことはできません。

金融口座の閉鎖は、Transactions などの関連オブジェクトのデータ保管に影響を及ぼしません。

APIを使用した FinancialAccount の閉鎖

POST/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close を使用し、関連付けられた ID の金融口座を閉鎖することが可能です。ヘッダー値として、関連付けられた連結アカウントの ID を含めます。

Command Line
curl https://api.stripe.com/v1/treasury/financial_accounts/{{FINANCIAL_ACCOUNT_ID}}/close \
  -usk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST" \
  -H "Stripe-Account: {{CONNECTED_STRIPE_ACCOUNT_ID}}"

レスポンスは、アクションを確認する、 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 サポートはお客様と協力して、売り手やサービスプロバイダーに支払うべき残金を返金し、残高がマイナスになっている解約された口座を修復します。金融口座の解約時に転送設定を含めると、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 の配列に変更が加えられます。