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 でのアカウント作成について

When you create an Account, you must provide identifying information about the entity it represents and define one or more configurations that control its behavior.

本人確認情報

Populate the identity hash with information about the individual or business that the Account represents. The specific parameters depend on the nature of the entity.

法人タイプ:

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

You can add a representative person to an Account by creating an associated Person object, as in the following example.

設定

Each Account has one or more configurations that represent different business personas, such as a merchant or customer. They define how the Account interacts with Stripe products.

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

Populate the configuration parameter for the Account with one or more of the following configuration types, depending on the functionality you want to provide.

購入者

The customer configuration allows a connected account to make payments to your platform and activates functionality in products such as Billing. It includes the automatic_indirect_tax capability, helps you collect the information you need to calculate taxes on the invoices, subscriptions, and payment links for the Account.

加盟店

The merchant configuration allows the controlling platform to create charges for the Account. It includes the card_payments capability, which is required for the Account to accept card payments.

受取人

The recipient configuration allows an Account to receive funds other than direct payments, such as Transfers or Global Payouts. The configuration includes the stripe_balance.stripe_transfers capability, which allows the Account to hold a Stripe balance and receive transfers. The stripe_balance.stripe_transfers capability is required for functionality such as destination charges.

ケイパビリティの有効化

To activate a capability, you must first request it by setting its requested property to true. That triggers collection of the capability’s requirements, which is handled by Stripe or your platform, depending on the responsibilities properties for the Account. Requirements can involve identity and compliance documentation, and risk data. When Stripe verifies that a capability’s requirements are fulfilled, it becomes active.

要件

Requirements describe the information required by Stripe to enable capabilities for the Account, and can include:

情報の種類
Stripe が情報を必要とする理由
要件が期限を過ぎているかどうか (「期限」は日付や、支払い額などの他のタイプのしきい値にすることができます)。
Consequences that Stripe imposes at the deadline if we can’t verify the information with acceptable documentation, such as suspending certain functionality or stopping payouts from the Stripe balance for the Account
アクションの実行者

会社代表者

Some capabilities might require you to create a Person object for the Account with relationship.representative set to true.

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

The following example requests the stripe_balance.stripe_transfers capability, which belongs to the recipient configuration. It assumes that the Account already has the recipient configuration.

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

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

In the example response, the stripe_balance.stripe_transfers capability has been requested, but its requirements are past due. Because the request didn’t ask for the customer or merchant configurations, they return null values even if they’re defined on the Account.

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
      }
    }
  }
}

The following variables affect the requirements imposed on an Account:

リクエスト済みケイパビリティ
The origin country for the Account
The entity type for the 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 パラメーターで参照できます。

A request with a customer parameter can accept the ID of a v2 Account, but you must provide it in the customer_account parameter instead of the customer parameter. The Account must have the customer configuration.
A request with an account parameter can accept the ID of any v2 Account in that parameter.

Accounts v1 ユーザー向けの情報

If your platform currently uses Accounts v1 and Customers v1, you can start using Accounts v2 in addition to them. However, you can’t use API v2 to manage Account and Customer objects created in API v1. Your platform must handle v1 and v2 objects separately.

プレビューに関する考慮事項

Accounts v2 では、プラットフォームでの決済を直接徴収するビジネスごとに、単一の設定可能な口座を使用できます。プレビューリリースでは、プラットフォームでの金融口座、Issuing、またはプレビュー中の決済手段には対応していません。Accounts v1 では、プラットフォーム、Issuing、またはプレビューでの決済手段用の金融口座を引き続き使用できます。

Connect プラットフォームの Accounts v2 はダッシュボードから有効にします。

メモ