Accounts v2 API公開プレビュー

Accounts v2 API を使用して、Stripe で連結アカウントを代表する方法をご紹介します。

ページをコピー

Accounts v2 API を使用すると、Stripe でユーザーを 1 つの事業体として表すことができます。

この API 構造では以下の機能が提供されます。

連結アカウントを代表する単一の事業体 (アクティビティは複数の設定間で共有)
アカウントを代表する個人または会社の構造化された ID データ
製品間での導入とアップグレードをサポートする変数設定
特定の要件に依存する設定固有の機能を表すケイパビリティ

Account の呼び出しでデータが返される仕組み

デフォルトでは、Accounts v2 は、実際の値に関係なく特定のプロパティの戻り値と他のプロパティの null を呼び出します。追加のプロパティ値を取得するには、include パラメーターを使用してリクエストを行います。

次の例では、含める戻り値のプロパティを指定せずに Account を作成しています。

レスポンスは、デフォルトで返されるプロパティの値のみを返します。他のプロパティ (リクエストによって値が割り当てられたものも含む) に対して null が返されます。

Response with no include
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer"
  ],
  "created": "2024-07-07T21:41:41.132Z",
  "display_name": "Furever",
  "configuration": null,
  "contact_email": "contact@test.com",
  "requirements": null,
  "identity": null,
  "defaults": null,
  "livemode": false
}

レスポンスに追加のプロパティを設定するには、それらを include パラメーターで指定します。設定の場合は、個々の設定タイプを明示的に指定する必要があります。リクエストされていない設定は、そのデータに関係なく null 値を返します。

次の例では customer 設定と merchant 設定を割り当てていますが、include パラメーターでは customer 設定のみリクエストされています。

このレスポンスは、リクエストで値が指定されていても、include 配列から configuration.merchant を省略すると merchant 設定に対して null 値が返されることを示しています。null 値は、リクエストの include パラメーターでそのプロパティが指定されていないことを示すにすぎません。

Response with include but omitting merchant
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "customer",
    "merchant"
  ],
  "configuration": {
    "customer": {
      "automatic_indirect_tax": {
        "exempt": "none",
        "ip_address": null,
        "location": null,
        "location_source": "identity_address"
      },
      "billing": {
        "default_payment_method": null,
        "invoice": {
          "custom_fields": [],
          "footer": null,
          "next_sequence": 1,
          "prefix": "KD5JNJLZ",
          "rendering": null
        }
      },
      "capabilities": {
        "automatic_indirect_tax": {
          "requested": true,
          "status": "restricted",
          "status_details": [
            {
              "code": "requirements_past_due",
              "resolution": "provide_info"
            }
          ]
        }
      },
      "shipping": null,
      "test_clock": null
    },
    "merchant": null,
    "recipient": null
  },
  "requirements": "{...}"
}

API v2 でのアカウント作成について

Account を作成する際に、アカウントを代表する事業体の本人確認情報を提供し、アカウントの動作を制御する設定を 1 つ以上定義する必要があります。

本人確認情報

Account を代表する個人または会社の情報を identity ハッシュに入力します。具体的なパラメーターは、事業体の性質によって異なります。

法人タイプ:

個人の権限で行動している人物の場合は、entity_type を individual に設定し、individual パラメーターに入力します。代表者と会社の間に法的な区別がなく、その個人が会社を所有および運営している場合は、business_details.structure を sole_proprietorship に設定します。

代表者を Account に追加するには、次の例のように、アカウントに関連付ける Person オブジェクトを作成します。

設定

各 Account には、加盟店や顧客などのビジネスペルソナが 1 つ以上設定されています。これらは、Account が Stripe プロダクトにおいてどのように作用するかを定義します。

各設定タイプには特定のケイパビリティが含まれており、関連する要件が満たされると、設定固有の機能が有効になります。ケイパビリティは、リクエストを行い、そのケイパビリティの要件の収集がトリガーされると有効になります。ケイパビリティは、要件が満たされていることを Stripe が確認すると有効になります。

提供する機能に応じて、Account の configuration パラメーターに以下の設定タイプを 1 つ以上入力します。

購入者

customer 設定を有効にすると、連結アカウントはプラットフォームへの支払いが可能になるほか、Billing などのプロダクトの機能が有効になります。これには automatic_indirect_tax ケイパビリティが含まれており、Account の請求書、サブスクリプション、決済用リンクの税金を計算するために必要な情報を収集するのに役立ちます。

加盟店

merchant 設定を有効にすると、管理プラットフォームが Account のために請求を作成できるようになります。これには、Account がカード支払いを受け付けるために必要な card_payments ケイパビリティが含まれています。

受取人

recipient 設定を有効にすると、Account がダイレクト支払い以外の方法 (Connect プラットフォームからの入金など) で売上を受け取れるようになります。これには stripe_balance.stripe_transfers ケイパビリティが含まれており、Account の Stripe 残高で売上の送金を受け取れるようになります。また、デスティネーション支払いなどの機能を利用する場合にも必要です。

ケイパビリティの有効化

ケイパビリティを有効にするには、まず requested プロパティを true に設定してからリクエストを行う必要があります。これにより、ケイパビリティの要件の収集がトリガーされ、Account の responsibilities プロパティに応じて、Stripe またはプラットフォームによって処理されます。要件には、本人確認および法令遵守に関するドキュメント、およびリスクデータが含まれます。Stripe がケイパビリティの要件が満たされていることを確認すると、そのケイパビリティは有効になります。

要件

要件は、Account のケイパビリティを有効にするために Stripe が必要とする情報を記述したもので、以下を含めることができます。

情報の種類
Stripe が情報を必要とする理由
要件が期限を過ぎているかどうか (「期限」は日付や、支払い額などの他のタイプのしきい値にすることができます)。
特定の機能の一時停止や Account の Stripe 残高からの入金停止など、受け入れ可能な書類でこれらの情報を確認できなかった場合に、期限に Stripe が及ぼす影響
アクションの実行者

会社代表者

一部のケイパビリティは、relationship.representative を true に設定して、Account に Person オブジェクトを作成する必要があります。

ケイパビリティ固有の影響に加えて、ケイパビリティに期限を過ぎた要件がある場合、その status は restricted になり、status_details.code は requirements_past_due になります。

次の例では、recipient 設定に属する stripe_balance.stripe_transfers ケイパビリティをリクエストしています。Account にはすでに recipient 設定があることを前提としています。

To see all the requirements for an Account’s requested capabilities, retrieve the Account and specify both requirements and the assigned configuration types in the include parameter.

次の例では、recipient 設定に属するケイパビリティのステータスと要件が返されています。

レスポンスの例では、stripe_balance.stripe_transfers ケイパビリティがリクエストされていますが、その要件は期限を過ぎています。リクエストが customer または merchant の設定を要求していないため、Account で定義されている場合でも null 値が返されます。

Capability activation response showing requirements
{
  "id": "acct_123",
  "object": "v2.core.account",
  "applied_configurations": [
    "recipient"
  ],
  "configuration": {
    "customer": null,
    "merchant": null,
    "recipient": {
      "capabilities": {
        ...
        "stripe_balance": {
          "payouts": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          },
          "stripe_transfers": {
            "requested": true,
            "status": "restricted",
            "status_details": [
              {
                "code": "requirements_past_due",
                "resolution": "provide_info"
              }
            ]
          }
        }
      },
      ...
    }
  },
  "contact_email": "furever_contact@example.com",
  "created": "2025-04-01T20:29:43.000Z",
  "dashboard": "full",
  "identity": null,
  "defaults": null,
  "display_name": "Furever",
  "metadata": {},
  "requirements": {
    "collector": "stripe",
    "entries": [
      {
        "awaiting_action_from": "user",
        "description": "identity.business_details.address.country",
        "errors": [],
        "impact": {
          "restricts_capabilities": [
            {
              "capability": "card_payments",
              "configuration": "merchant",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.stripe_transfers",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            },
            {
              "capability": "stripe_balance.payouts",
              "configuration": "recipient",
              "deadline": {
                "status": "past_due"
              }
            }
          ]
        },
        "minimum_deadline": {
          "status": "past_due"
        },
        "reference": null,
        "requested_reasons": [
          {
            "code": "routine_onboarding"
          }
        ]
      },
    ...
    ],
    "summary": {
      "minimum_deadline": {
        "status": "past_due",
        "time": null
      }
    }
  }
}

以下の変数は、Account に課せられる要件に影響します。

リクエスト済みケイパビリティ
Account の所在国
Account の法人タイプ

要件の impact は、その要件が期限を過ぎた場合にケイパビリティがどのように影響を受けるかを示します。その minimum_deadline.status は、impact にリストされているすべてのケイパビリティの中で最も早い期限ステータスです。要件の収集に優先順位を付ける場合、影響ごとに deadline.status を調べます。

ほとんどの Stripe ユーザーは、アカウント登録時に要件を満たしています。使用するアカウント登録フローに関係なく、次の 2 つの方法のいずれかを選択できます。

増分:アカウント登録時に最小要件、つまりステータスが currently_due または past_due の要件のみ収集します。
先行:期限のステータスに関係なく、アカウント登録時にすべての要件を収集します。

要件の更新を監視する

法律や規制は随時変更される可能性があるため、Stripe では法令遵守およびリスク管理システムを継続的に更新しています。これは、連結アカウントの機能の要件に影響を与える可能性があります。連結アカウントのビジネスに支障をきたさないようにするには、機能と要件のステータスを継続的に監視し、必要に応じて要件を更新するプロセスを実装する必要があります。

v1 のリクエストで Accounts v2 オブジェクトを参照する

v2 アカウントの ID は、別の Stripe API の account パラメーターまたは customer_account パラメーターで参照できます。

customer パラメーターを含むリクエストは、v2 Account の ID を受け入れることができますが、customer パラメーターではなく customer_account パラメーターで指定する必要があります。Account には　customer 設定が必要です。
account パラメーターを含むリクエストは、そのパラメーターで任意の v2 Account の ID を受け入れることができます。

Accounts v1 ユーザー向けの情報

プラットフォームで現在 Accounts v1 や Customers v1 を使用している場合は、それらに加えて Accounts v2 の使用を開始できます。ただし、API v1 で作成された Account オブジェクトと Customer オブジェクトを API v2 で管理することはできません。プラットフォームでは、v1 のオブジェクトと v2 のオブジェクトを別々に処理する必要があります。

Preview considerations

Accounts v2 allows you to use a single, configurable account for each business on your platform that collects payments directly. The preview release doesn’t support Treasury, Issuing, or payment methods that are in preview. You can still use Treasury, Issuing, or payment methods in preview with Accounts v1.

Enable Accounts v2 for your Connect platform from your Dashboard.

注