# Connect および Accounts v2 API

Stripe 全体で統一された ID を使用して連結アカウントを作成します。

Connect プラットフォームでは、連結アカウントが決済を受け付けるようにします。また、連結アカウントが商品を購入したりサービスを契約したりする際に、その決済を受け付けることもできます。Accounts v1 API では、こうした購入やサブスクリプションを連結アカウントに関連付けるために、別途 `Customer` オブジェクトを作成し、それを連結アカウントの `Account` オブジェクトに手動で関連付ける必要がありました。

Accounts v2 API では、連結アカウントとのすべてのやり取りをサポートする 1 つの `Account` オブジェクトを作成できるため、`Customer` オブジェクトを別途作成してトラックする必要はありません。

## Accounts v2 API

Accounts v2 API で以下のことが可能になります。

- **柔軟なアカウント設定**: 連結アカウントのケイパビリティと Stripe 機能との互換性を有効化または変更するには、アカウントの設定を更新します。各ケイパビリティは特定の設定に属します。
- **一元化された本人確認データ**: 追加機能を有効にするために既存のアカウントに設定を追加する場合、そのアカウントがすでに提供している要件を再徴収する必要はありません。
- **連結アカウントと顧客のための単一の API**: ほとんどの場合、アカウントオブジェクトで任意の顧客を表すことができます。これにより、Accounts v2 API を使用して、連結アカウントと顧客の両方を管理できます。Customers API を使用する必要はまったくなくなりました。

## Accounts v2 を使用して連結アカウントを表現する

Accounts v2 API では、1 つ以上の構成をアカウントに割り当てて、さまざまな機能を有効にします。以下に例を示します。

- `merchant` 設定を割り当てて、アカウントが顧客から決済を受け付けるようにします。`merchant` 設定には、`card_payments` と `stripe_balance.payouts` (v1 `payouts` の後継) ケイパビリティが含まれます。
- `customer` 設定を割り当てて、アカウントへの請求を顧客として行います。サブスクリプションの作成時に、Customer オブジェクトではなく `customer` 設定のアカウントを使用できます。
- Account が送金を受け取れるようにするため、`recipient` 構成を割り当てます。`recipient` 構成には、v1 の `transfers` を置き換える `stripe_balance.stripe_transfers` (間接請求を利用するために必須) ケイパビリティが含まれます。

次の例では、API v2 を使用してアカウントを作成します。アカウントオブジェクトの構造は、API v1 のアカウントオブジェクトの構造とは異なります。

> #### API v2 レスポンス構造
> 
> デフォルトでは、Accounts v2 API コールは、実際の値に関係なく、特定のプロパティに対しては値、その他のプロパティに対しては null を返します。追加のプロパティ値を取得するには、[include パラメータ](https://docs.stripe.com/api-includable-response-values.md)を使用してリクエストします。

```curl
curl -X POST https://api.stripe.com/v2/core/accounts \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-01-28.clover" \
  --json '{
    "contact_email": "jenny.rosen@example.com",
    "display_name": "Jenny Rosen",
    "dashboard": "full",
    "identity": {
        "business_details": {
            "registered_name": "Furever"
        },
        "country": "us",
        "entity_type": "company"
    },
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        },
        "merchant": {
            "capabilities": {
                "card_payments": {
                    "requested": true
                }
            }
        }
    },
    "defaults": {
        "currency": "usd",
        "responsibilities": {
            "fees_collector": "stripe",
            "losses_collector": "stripe"
        },
        "locales": [
            "en-US"
        ]
    },
    "include": [
        "configuration.customer",
        "configuration.merchant",
        "identity",
        "requirements"
    ]
  }'
```

v1 API では、連結アカウントが決済を受け付けるためのアカウントオブジェクトと、その同じビジネスをプラットフォームに対する支払いに関連付ける個別の `Customer` オブジェクトを作成する必要があります。アカウント v1 と顧客 v1 には明示的な関係がないため、これらのオブジェクトを別々に管理し、アカウント ID と顧客 ID のマップを保持する必要があります。

### アカウントを作成する

```curl
curl https://api.stripe.com/v1/accounts \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d country=US \
  -d "controller[fees][payer]=application" \
  -d "controller[losses][payments]=application" \
  -d "controller[stripe_dashboard][type]=express"
```

### 顧客を作成する

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=Jenny Rosen" \
  --data-urlencode "email=jenny.rosen@example.com" \
  -d "metadata[account_id]]=acct_1234"
```

## 顧客としてアカウントを使用する

`customer` パラメータを受け入れる API はすべて、`customer_account` パラメータも受け入れます。顧客設定のアカウント ID を渡すことができます。

```curl
curl https://api.stripe.com/v1/setup_intents \
  -u "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2025-09-30.preview" \
  -d customer_account=acct_123 \
  -d "payment_method_types[]=card" \
  -d confirm=true \
  -d usage=off_session
```

[Accounts を顧客として使用する](https://docs.stripe.com/connect/use-accounts-as-customers.md)方法の詳細をご覧ください。

## Accounts v1 と Customers v1 を使用する Connect

Stripe は引き続き Accounts v1 API と Customers v1 API をサポートしています。ただしAccounts v1 API で作成されたアカウントを、Accounts v2 API で管理できます。これには、それらのアカウントに `customer` 構成を割り当てることも含まれます。

## 考慮事項

Stripe では、両方の Accounts API バージョンを同時に無期限に維持することは推奨されていません。

プラットフォームが [OAuth を使用](https://docs.stripe.com/stripe-apps/api-authentication/oauth.md)して連結アカウントで認証する場合は、引き続き v1 API を使用します。