コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン

メモ

このページはまだ日本語ではご利用いただけません。より多くの言語で文書が閲覧できるように現在取り組んでいます。準備が整い次第、翻訳版を提供いたしますので、もう少しお待ちください。

既存の連携機能で Accounts v2 API を使用する

Accounts v1 と Customers v1 で構築された組み込みを更新する方法をご紹介します。

Accounts v1 と Customers v1 を連結するプラットフォームのインテグレーションを更新して、次の Accounts v2 の機能にアクセスする場合は、このガイドに従ってください。

  • 顧客オブジェクトを作成せずに、連結アカウントをプラットフォームに対する支払いに関連付けます。
  • 連結アカウントが Stripe 残高を使用してプラットフォームに支払いを行えるようにすることで、ネットワークコストを回避します。
  • 連結アカウントが v2 金融口座を使用してプラットフォームで売上を保持できるようにします。

Accounts v2 の機能が必要ない場合は、Accounts v1 と Customers v1 のプラットフォーム導入を引き続き使用できます。

すべてのアカウントに v2 エンドポイントを使用する

Accounts v2 API は、既存の v1 Accounts に変更を加えることなく使用することができます。

アカウント作成の遅延

新しい v1 Account は、Accounts v2 エンドポイントで使用できるようになるまでに 10 分ほどかかる場合があります。Account が API v2 リクエストに対応する準備ができると、v2.core.account.created Webhook イベントを送信します。

顧客設定を追加する

Account にcustomer 構成を追加すると、サブスクリプション作成など、Customer ID を受け付ける任意の API リクエストで Account ID を指定できるようになります。その場合、customer パラメータに Customer ID を指定する代わりに、customer_account パラメータに Account IDを指定します。

次の例では、Accounts v2 API を使用して既存の v1 アカウントに customer 設定を追加し、その Stripe 残高を使用してアカウントへの支払いを行う既存のサブスクリプションを更新します。

  1. Account を更新し customerの 設定を追加します。
Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "configuration": {
        "customer": {
            "capabilities": {
                "automatic_indirect_tax": {
                    "requested": true
                }
            }
        }
    },
    "include": [
        "configuration.customer",
        "identity"
    ]
  }'
  1. Retrieve the connected account to confirm it has the card_payments capability in the merchant configuration. This capability must be active in order to use the Stripe balance as a payment method.
Command Line
cURL
No results
curl -X POST https://api.stripe.com/v2/core/accounts/acct_1abc \
  -H "Authorization: Bearer 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
" \
  -H "Stripe-Version: 2025-12-15.preview" \
  --json '{
    "include": [
        "configuration.merchant",
        "identity",
        "defaults"
    ]
  }'
  1. Add the connected account’s Stripe balance as a payment method.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_account=acct_1abc \
  -d "payment_method_types[]"=stripe_balance \
  -d confirm=true \
  -d usage=off_session \
  -d "payment_method_data[type]"=stripe_balance
  1. Create a subscription that charges the connected account using its Stripe balance.
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer_account=acct_1abc \
  -d payment_behavior=default_incomplete \
  -d "items[0][price]"={{PRICE_ID}} \
  -d "payment_settings[save_default_payment_method]"=on_subscription

この連結アカウントからサブスクリプション支払いを受け付けるために、Customer オブジェクトを別途管理する必要がなくなりました。

導入を段階的に移行

Accounts v1 API と v2 API の両方を Accounts で使用できるため、ビジネスニーズに合ったペースで導入を更新できます。たとえば、次のようなことが可能です。

  • API v1を使用して作成された Accounts の /v2/core/accounts エンドポイントを呼び出します。
  • API v2 を使用して作成されたAccountsの /v1/accounts エンドポイントを呼び出します。
  • 顧客の設定で Accounts の /v1/customers エンドポイントを呼び出します。
  • Events API v2 を使用して、いずれかの API バージョンを使用して作成されたオブジェクトの変更を監視します。

これらの互換性により、本番環境で複数バージョンを維持したり、全体を一度に更新したりすることなく、段階的に更新することができます。

次の注文で導入を更新することをお勧めします。

  1. v2 イベントをリッスンする新しいエンドポイントを設定します。
  2. Account と Customer コールを create、/v2/core/accounts を使用して顧客設定のアカウントを作成します。
  3. Account を変更し、Customer が /v2/core accounts を使用するようにコールを update します。
  4. AccountとCustomerコールを /v2/core/accounts を使用するようにretrieve します。

v1 エンドポイントで v2 アカウントを使用する

v1 エンドポイントで v2 オブジェクトを参照すると、レスポンスは v1 オブジェクト構造の v2 データを返します。たとえば、

  • /v1/accounts エンドポイントで v2 Account を参照すると、v1 Account の構造でデータが返されます。
  • /v1/customers エンドポイントでv2 Account を参照すると、v1 Customer の構造でデータが返されます。これには、customer ID と customer_account ID の両方が含まれます。
Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/customers/acct_1abc \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d business_name="Furever Plus"

Customers v1 API で顧客設定 Accounts を使用できますが、Accounts v2 API で v1 の Customers を参照することはできません。顧客データを新しい顧客設定 Account に移行するか、既存の連結アカウントを更新して customer 設定を追加する必要があります。

Webhook イベント

アカウントは、v1 (スナップショット)イベントとv2 (軽量) イベントの両方を送信します。Accounts v2 イベントを受信するための新しいエンドポイントを設定することを推奨します。

  1. Stripe ダッシュボードで、ナビゲーションメニューのフッターにある開発者をクリックして開発者メニューを開き、Webhook を選択します。
  2. 送信先を追加 をクリックします。
  3. Events from セクションで、Connected accounts を選択します。
  4. 詳細設定を表示を選択します。Payload style セクションで、Thin を選択します。
  5. Events フィールドで、対象となる Account オブジェクトのバージョンに対応するイベントを 1 つ以上選択します。
    • v1 の場合は、「v1」と入力して、v1 オブジェクトのイベントタイプを検索します。v1.account.updated を選択します。
    • v2 の場合は、「v2」と入力して、v2 オブジェクトのイベントタイプを検索します。v2.core.account.updated またはその他の v2.core.account[*].updated イベントを選択します。
  6. インタラクティブな Webhook エンドポイントビルダーに従って、イベントの送信先の設定を続けます。

たとえば、いずれかのバージョンのアカウントを更新すると、次の情報が送信されます。

  • v1 account.updated イベント
  • v2 v1.account.updated イベント
  • v2 v2.core.account.updated イベント

Events v2 APIのアカウントバージョンの違い

v2.core.account のイベントタイプの多くは、v1.account のイベントタイプと直接対応していません。たとえば、Account のいずれかのプロパティを変更すると、v1 では v1.account.updated イベントが発生します。一方、v2 では同じ操作でもv2.core.account[identity].updated や v2.core.account[configuration.recipient].updated のように、プロパティごとのイベントが発生する場合があります。

v2.core.account.updated イベントは、より具体的な更新イベントのいずれかをトリガーしない、ダッシュボードや display_name などのトップレベルプロパティの更新に対してのみ送信されます。

Accounts API v2の制限

Accounts v1 は、次の場合に使用する必要があります。

  • OAuth を使用して連結されたアカウント
  • 受取人利用規約に署名したアカウント
  • 次のケイパビリティをリクエストまたは管理するには、次の手順に従います。
    • treasury
    • card_issuing_*
    • legacy_payments などの非推奨ケイパビリティ
    • 非推奨支払い方法
    • 支払い方法の公開または非公開プレビュー

海外入金

Global Payouts を使用して海外に送金します。