Stripe Apps の埋め込み導入ガイド非公開プレビュー

Connect.js を設定して、連結アカウントのダッシュボード機能をウェブサイトに追加することができます。

埋め込み Stripe Apps はプライベートプレビュー版コンポーネントを使用するため、Stripe SDK のプレビューバージョンを使用する必要があります。プライベートプレビュー版コンポーネントの詳細をご覧ください。

Stripe は以下のアプリの実装をサポートしています。

選択したアプリのアプリインストール埋め込みコンポーネントを表示します。アプリをインストールすると、サードパーティーアプリに Stripe ユーザーデータへのアクセス権が付与され、プラットフォーム、Stripe、サードパーティーアプリ間の接続が作成されます。コンポーネントには uninstalled と installed の 2 つの状態があります。インストールイベントトリガーをリッスンして、カスタムの UX フローを構築するか、自社のバックエンドで更新を行います。

アカウントセッションの作成時に、components パラメーターで app_install と app_viewport を指定して、アプリのインストールと表示コンポーネントを有効にします。allowed_apps の features パラメーターを指定して、表示するアプリを有効にしてください。

curl https://api.stripe.com/v1/account_sessions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Version: 2025-06-30.basil; embedded_connect_beta=v2;" \
  -d account={{CONNECTED_ACCOUNT_ID}} \
  -d "components[app_install][enabled]"=true \
  -d "components[app_install][features][allowed_apps][]"=APP_ID \
  -d "components[app_viewport][enabled]"=true \
  -d "components[app_viewport][features][allowed_apps][]"=APP_ID

アカウントセッションを作成して、ConnectJS を初期化すると、フロントエンドにアプリインストールコンポーネントを表示できます。

const appInstall = stripeConnectInstance.create('app-install');
appInstall.setApp('{{APP_ID}}');
container.appendChild(appInstall);

この埋め込みコンポーネントは、次のパラメーターに対応します。

現在の、または更新されたインストールの状態に基づいて、カスタムの動作を設定できます。

// index.html
<div id="app-install-container"></div>

// index.js

// Do something when install state fetched on render
const handleAppInstallFetched = (response) => {
  console.log(`Install state fetched for app  ${response.appId} to ${response.state}`);
};

// Do something when install state changes
const handleAppInstallChanged = (response) => {
  console.log(`Install state changed for app  ${response.appId} to ${response.state}`);
};


const container = document.getElementById('app-install-container');
const appInstall = stripeConnectInstance.create('app-install');
appInstall.setApp('{{APP_ID}}');
appInstall.setOnAppInstallStateFetched(handleAppInstallFetched);
appInstall.setOnAppInstallStateChanged(handleAppInstallChanged);
container.appendChild(appInstall);

選択したアプリのアプリビューポートの埋め込みコンポーネントを表示して、アプリのコア機能 (OAuth を使用したソフトウェアアカウントへの接続、アカウント登録、サービスの設定、取引の同期状態など) を有効にします。オプションの HTML 属性として user_id (お客様のプラットフォームで表されるビジネス) を渡します。サードパーティーアプリはこれを使用して、OAuth の後にユーザーダッシュボードへリダイレクトされる動的 URL を作成します。

const appViewport = stripeConnectInstance.create('app-viewport');
appViewport.setApp('{{APP_ID}}');
appViewport.setAppData({userId: '{{PLATFORM_USER_ID}}'});
container.appendChild(appViewport);

この埋め込みコンポーネントは、次のパラメーターに対応します。

To ensure that your selected app properly processes transaction data, you must update the destination charge on the connected account by using the standardized data schema. It’s crucial that your platform sends at least a Customer object (specifically the customer ID) with each charge event.

This requirement is important because the charge.updated event might be sent multiple times for a single transaction. However, the third-party app only reads and processes events that include a customer ID. Always include the customer ID in the payload to confirm that the app processes the corresponding transaction. You have three scenarios that require you to update your destination charge:

• 1 回限りの支払いの完了
• 継続支払いの完了
• 支払いの返金

次のコードスニペットの例では、対象となるデスティネーション支払いに移動し、スキーマごとに更新する方法を示しています。

1. 取引からデスティネーション支払いまで追跡します

const paymentOnPlatform = await StripeClient.paymentIntents.retrieve(
  "pi_3N6JL7LirQdaQn8E1Lpn7Dui",
);

const latestCharge = await StripeClient.charges.retrieve(
  paymentOnPlatform.latest_charge as string,
);

const transfer = await StripeClient.transfers.retrieve(
  latestCharge.transfer as string,
);


const payment = await StripeClient.charges.retrieve(
  transfer.destination_payment as string,
    undefined,
    {
        stripeAccount: transfer.destination as string,
      },
  );

1. 顧客を作成したら、関連する顧客 ID とメタデータで支払いを更新します。データの受け渡しやアプリの同期を行うには、顧客はプラットフォームではなく、連結アカウントに属している必要があります。

const customer = await StripeClient.customers.create(
      {
        email: `jenny.rosen@example.com`,
        name: "Jenny Rosen",
	 address.city: "Brothers"
	 Address.state: "Oregon"
	 address.country: "USA"
	 address.line1: "27 Fredrick Ave"
	 address.postal_code: "97712"
       	 metadata: {
 	   platform_customer_ID: "K-123456"
	 },
      },
      {
        stripeAccount: accountId,
      },
    );
    const payment = await StripeClient.charges.update(
      id,
      {
        customer: customer.id,
        metadata: {
          product_name: "Creative writing course for PMs",
          platform_product_ID: "P-123456"
          platform_order_ID: "O-123456"
        },
      },
      {
        stripeAccount: accountId,
      },
    );

システムの埋め込みによって、Stripe に保存されている支払い、顧客、商品のすべてのデータにアクセスできます。以下のメタデータスキーマを使用して、任意のプラットフォームデータをアプリに渡すことができます。