Treasury 金融口座を使用する

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

Treasury への API アクセスを獲得した後、Stripe は金融口座をプラットフォームアカウントに関連付け、プラットフォーム上の対象の連結アカウントに金融口座を準備できるようになります。各金融口座には、それが関連付けられているアカウントの残高とは別個の、明確な資金の残高があります。たとえば、プラットフォーム上の連結アカウントの所有者が、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 を連結アカウントと関連付けます。

連結アカウントには、Stripe-Account ヘッダーの値として同じ連結アカウント ID を指定することで、複数の金融口座を関連付けることができます。1 つの連結アカウントに関連付けることができるのは最大で 1 個の金融口座です (解約済みの金融口座はこの上限に影響しません)。口座のしきい値をより高く設定する必要がある場合は、treasury-support@stripe.com にお問い合わせください。

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

JSON (コメント付き)
{
  "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 ハッシュには、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 を作成しようとするとエラーが発生します。

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

拡張された口座を示すレスポンス
{
  "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 日間アクティビティがありません。または、入金されるデビットとクレジットを転送する別の金融口座または外部口座を指定することもできます。

警告

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

金融口座を閉鎖するには、treasury-support@stripe.com に連絡して、閉鎖する FinancialAccount ID と閉鎖の理由をお知らせください。Treasury コンプライアンスガイドラインに記載されているように、口座閉鎖についてユーザーに通知する必要があります。

金融口座の閉鎖は、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_4eC39HqLyjWDarjtT1zdp7dc
: \
  -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 の配列に変更が加えられます。

注