# Stripe Apps の埋め込み導入ガイド Stripe Apps の埋め込みコンポーネントを使用して、顧客がサードパーティーアプリケーションで支払いデータを管理できるようにします。 顧客は、ビジネスワークフローを完了するためにすでに使用しているツールで、支払いデータをすぐに利用できることを期待しています。アプリの埋め込みコンポーネントを使用すると、顧客は Stripe でサードパーティーのアプリケーションを使用できるようになります。 アプリの埋め込みコンポーネントを使用すると、Stripe 向けに構築されたシステムをプラットフォームに埋め込むことができ、顧客は Stripe のサイトにとどまったまま任意のサードパーティーアプリケーションを使用できるようになります。QuickBooks や Xero などのアプリケーションとデータを直接同期できる、事前構築済みの UI コンポーネントをご使用ください。 ## Connect の埋め込みコンポーネントを導入する [Connect.js を設定](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions)して、連結アカウントのダッシュボード機能をウェブサイトに追加することができます。 埋め込み Stripe Apps はプライベートプレビュー版コンポーネントを使用するため、Stripe SDK のプレビューバージョンを使用する必要があります。[プライベートプレビュー版コンポーネント](https://docs.stripe.com/connect/supported-embedded-components.md#preview-components)の詳細をご覧ください。 ## 実装するアプリを選択する Stripe は以下のアプリの実装をサポートしています。 | 実装可能アプリ | アプリ ID | | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | [QuickBooks Sync by Acodei](https://docs.stripe.com/stripe-apps/embedded-apps/accounting-integrations.md#quickbooks-sync-by-acodei) | com.example.acodeistripeapp | | [Xero sync by Xero](https://docs.stripe.com/stripe-apps/embedded-apps/accounting-integrations.md#xero) | com.xero.stripeapp | | [Mailchimp](https://docs.stripe.com/stripe-apps/embedded-apps/marketing-integrations.md#mailchimp) | mailchimp | ## アプリインストールを設定する 選択したアプリのアプリインストール埋め込みコンポーネントを表示します。アプリをインストールすると、サードパーティーアプリに Stripe ユーザーデータへのアクセス権が付与され、プラットフォーム、Stripe、サードパーティーアプリ間の接続が作成されます。コンポーネントには `uninstalled` と `installed` の 2 つの状態があります。インストールイベントトリガーをリッスンして、カスタムの UX フローを構築するか、自社のバックエンドで更新を行います。 [アカウントセッションの作成](https://docs.stripe.com/api/account_sessions/create.md)時に、`components` パラメーターで `app_install` と `app_viewport` を指定して、アプリのインストールと表示コンポーネントを有効にします。`allowed_apps` の `features` パラメーターを指定して、表示するアプリを有効にしてください。 ```curl curl https://api.stripe.com/v1/account_sessions \ -u "<>:" \ -H "Stripe-Version: 2026-03-25.preview; 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 を初期化](https://docs.stripe.com/connect/get-started-connect-embedded-components.md#account-sessions)すると、フロントエンドにアプリインストールコンポーネントを表示できます。 #### JavaScript ```js const appInstall = stripeConnectInstance.create('app-install'); appInstall.setApp('{{APP_ID}}'); container.appendChild(appInstall); ``` この埋め込みコンポーネントは、次のパラメーターに対応します。 #### HTML + JS | 方法 | タイプ | 説明 | | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | | `setApp` | `string` | 連結アカウントがインストールできるアプリの ID を設定します。[利用可能なアプリ](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select)のリストをご覧ください。 | #### React | React プロパティ | タイプ | 説明 | | ----------- | -------- | ---------------------------------------------------------------------------------------------------------------- | | `app` | `string` | 連結アカウントがインストールできるアプリの ID。[利用可能なアプリ](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select)のリストをご覧ください。 | 現在の、または更新されたインストールの状態に基づいて、カスタムの動作を設定できます。 #### JavaScript ```js // index.html
// 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); ``` #### HTML + JS | 方法 | 説明 | 変数 | | ----------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------- | | `setOnAppInstallStateFetched` | インストールのフェッチ時に、ユーザーがコールバック関数でカスタム動作を指定できるようにします。 | - `response.appId`:インストールされたアプリ - `response.state`:インストール状態 `INSTALLED | UNINSTALLED` | | `setOnAppInstallStateChanged` | インストール状態が変化したときに、ユーザーがコールバック関数でカスタム動作を指定できるようにします。 | - `response.appId`:インストールされたアプリ - `response.state`:インストール状態 `INSTALLED | UNINSTALLED` | #### React | React プロパティ | 説明 | 変数 | | -------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------- | | `onAppInstallStateFetched` | インストールのフェッチ時に、ユーザーがコールバック関数でカスタム動作を指定できるようにします。 | - `response.appId`:インストールされたアプリ - `response.state`:インストール状態 `INSTALLED | UNINSTALLED` | | `onAppInstallStateChanged` | インストール状態が変化したときに、ユーザーがコールバック関数でカスタム動作を指定できるようにします。 | - `response.appId`:インストールされたアプリ - `response.state`:インストール状態 `INSTALLED | UNINSTALLED` | ## アプリの設定 選択したアプリのアプリビューポートの埋め込みコンポーネントを表示して、アプリのコア機能 (OAuth を使用したソフトウェアアカウントへの接続、アカウント登録、サービスの設定、取引の同期状態など) を有効にします。オプションの HTML 属性として `user_id` (お客様のプラットフォームで表されるビジネス) を渡します。サードパーティーアプリはこれを使用して、OAuth の後にユーザーダッシュボードへリダイレクトされる動的 URL を作成します。 #### JavaScript ```js const appViewport = stripeConnectInstance.create('app-viewport'); appViewport.setApp('{{APP_ID}}'); appViewport.setAppData({userId: '{{PLATFORM_USER_ID}}'}); container.appendChild(appViewport); ``` この埋め込みコンポーネントは、次のパラメーターに対応します。 #### HTML + JS | 方法 | タイプ | 説明 | | ------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | | `setApp` | `string` | 連結アカウントがレンダリングできるアプリの ID を設定します。利用可能なアプリは、[Stripe Apps の埋め込み導入ガイド](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select)でご覧ください。 | | `setAppData` | `Record` | アプリが使用する、プラットフォームに関するデータを設定します。 | #### React | React プロパティ | タイプ | 説明 | | ----------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `app` | `string` | 連結アカウントがレンダリングできるアプリの ID。詳しくは、[利用可能なアプリ](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select)をご覧ください。 | | `appData` | `Record` | アプリが使用する、プラットフォームに関するデータ。 | ## on behalf of (OBO) の Connect 送信先のカスタマイズ 選択したアプリが取引データを適切に処理できるようにするには、標準化されたデータスキーマを使用して、連結アカウントのデスティネーション支払いを更新する必要があります。プラットフォームが、各支払いイベントとともに少なくとも[顧客](https://docs.stripe.com/api/customers/object.md)オブジェクト(具体的には顧客 ID) を送信することが重要です。 `charge.updated` イベントが 1 つの取引に対して複数回送信される可能性があるため、この要件は重要です。ただし、サードパーティーアプリは顧客 ID を含むイベントのみを読み取り、処理します。ペイロードには常に顧客 ID を含めて、アプリが対応する取引を処理することを確認します。デスティネーション支払いの更新が必要なシナリオが 3 つあります。 - 1 回限りの支払いの完了 - 継続支払いの完了 - 支払いの返金 #### 会計 | フィールドまたはキーの名前 | 形式 (標準の CSV ルールを適用) | 説明 | 必須 | | ---------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------- | | [charges.customer](https://docs.stripe.com/api/charges/object.md#charge_object-customer) | 文字列 (ID) | デスティネーション `Charge` オブジェクトに関連付けられた (連結アカウントに属する) Customer ID。このフィールドが存在しない場合、取引はアプリ (Xero や QBO など) と同期されません。 | 必須 | | [customer.name](https://docs.stripe.com/api/customers/object.md#customer_object-name) | 文字列 | 顧客の氏名 | | | [customer.email](https://docs.stripe.com/api/customers/object.md#customer_object-email) | 文字列 | 顧客のメールアドレス | | | [customer.address.<>](https://docs.stripe.com/api/customers/object.md#customer_object-address) | 文字列 (複数フィールド) | 顧客の住所 (請求先と配送先の両方で使用可能な住所) | | | `charges.metadata.[refund_amount]` | 文字列 (セント単位) | [charges.amount_refunded](https://docs.stripe.com/api/charges/object.md#charge_object-amount_refunded) のコピー (基本通貨の補助単位 (‘350’ = 3.50 USD)) | Quickbooks Online で Acodei による同期が必要 | | `charges.metadata.[refund_reason]` | 文字列 | 返金の理由 | | | `charges.metadata.[currency_converted]` | `true` | `false` | `null` | 通貨が換算されている場合は `true` に設定します (取引通貨が売上処理通貨と異なる場合など) | fees_names メタデータを使用する場合、Quickbooks Online で Acodei による同期が必要です | | `customer.metadata.[platform_customer_ID]` | 文字列 | プラットフォームのシステムに記録されている顧客 ID* | | | `charges.metadata.[platform_product_ID]` | 文字列、CSV 形式の商品 | プラットフォームのシステムに記録されている商品 ID | | | `charges.metadata.[platform_product_name]` | 文字列、CSV 形式の商品 | プラットフォームのシステムに記録されている商品名 | | | `charges.metadata.[platform_product_quantity]` | 文字列、CSV 形式の商品 | ID および名前の配列に対応する各商品の数量 | | | `charges.metadata.[platform_product_value]` | 整数、CSV 形式の商品 | 商品 ID および商品名に対応する個々の商品の金額 (価格またはコスト)。基本通貨の補助単位 (‘350’ = 3.50 USD) | | | `charges.metadata.[platform_product_tag]` | 文字列、CSV 形式の商品 | ID および名前の配列に対応する商品タグまたはカテゴリー | | | `charges.metadata.[platform_order_ID]` | 文字列 | プラットフォームのシステムに記録されている注文 ID | | | `charges.metadata.[platform_charge_ID]` | 文字列 | プラットフォームのシステムに記録され、ビジネスに表示される支払いまたは取引の ID | | | `charges.metadata.[fees_names]` | 文字列、CSV 形式の手数料 | Charge でキャプチャーされていない取引に関連してユーザーが支払う手数料 (経費) の名前 (クレジット処理手数料やプラットフォーム手数料など)。*このフィールドが入力されている場合、charges.application\_fee は無視されます。* | | | `charges.metadata.[fees_values]` | 整数、CSV 形式の手数料 | 支払いでキャプチャーされていない取引に関連して売ユーザーが支払う手数料 (経費) の金額 (クレジット処理手数料やプラットフォーム手数料など)。基本通貨の補助単位 (‘350’ = 350 USD) | | | `charges.metadata.[revenues_names]` | 文字列、CSV 形式の収益 | この取引 (支払い) に関連してビジネスが回収した手数料 (収益) のうち、支払いでキャプチャーされていない手数料 (コンビニ手数料やチップなど) | | | `charges.metadata.[revenues_values]` | 整数、CSV 形式の収益 | この取引 (支払い) に関連してビジネスが回収した手数料 (収益) の金額。基本通貨の補助単位 (‘350’ = 3.50 USD) | | | `charges.metadata.[total_tax]` | 整数 | この取引 (支払い) に係る税金の合計。基本通貨の補助単位 (‘350’ = 3.50 USD) | | | `charges.metadata.[tax_names]` | 文字列、CSV 形式の税金 | 取引に適用される税タイプ名　(例: ‘GST’、‘sales’)。配列で複数の税タイプに対応可能 | | | `charges.metadata.[tax_rates]` | 浮動小数点、CSV 形式の税金 | パーセント表示の税タイプの取引に適用される税率 (たとえば、‘3’ または ‘1.5’ は GST 3% および売上税 1.5% に相当します) | | | `charges.metadata.[tax_values]` | 文字列、CSV 形式の税金 | 特定の税タイプの取引に適用される税額。基本通貨の補助単位 (‘350’ = 3.50 USD) | | QuickBooks Sync by Acodei では、メタデータに記述されている返金額の支払いの更新も必要です。 #### マーケティング | フィールドまたはキーの名前 | 形式 (標準の CSV ルールを適用) | 説明 | 必須 | | ---------------------------------------------------------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------ | -- | | [charges.customer](https://docs.stripe.com/api/charges/object.md#charge_object-customer) | 文字列 (ID) | デスティネーション `Charge` オブジェクトに関連付けられた (連結アカウントに属する) Customer ID。このフィールドが存在しない場合、取引はアプリ (Xero や QBO など) と同期されません。 | 必須 | | [customer.name](https://docs.stripe.com/api/customers/object.md#customer_object-name) | 文字列 | 顧客の氏名 | | | [customer.email](https://docs.stripe.com/api/customers/object.md#customer_object-email) | 文字列 | 顧客のメールアドレス | | | [customer.address.<>](https://docs.stripe.com/api/customers/object.md#customer_object-address) | 文字列 (複数フィールド) | 顧客の住所 (請求先と配送先の両方で使用可能な住所) | | | `charges.metadata.[refund_amount]` | 文字列 (セント単位) | [charges.amount_refunded](https://docs.stripe.com/api/charges/object.md#charge_object-amount_refunded) のコピー | | | `charges.metadata.[refund_reason]` | 文字列 | 返金の理由 | | | `customer.metadata.[platform_customer_ID]` | 文字列 | プラットフォームのシステムに記録されている顧客 ID* | | | `charges.metadata.[platform_product_ID]` | 文字列、CSV 形式の商品 | プラットフォームのシステムに記録されている商品 ID | | | `charges.metadata.[platform_product_name]` | 文字列、CSV 形式の商品 | プラットフォームのシステムに記録されている商品名 | | | `charges.metadata.[platform_product_quantity]` | 文字列、CSV 形式の商品 | ID および名前の配列に対応する各商品の数量 | | | `charges.metadata.[platform_product_value]` | 文字列、CSV 形式の商品 | 商品 ID と商品名に対応する個々の商品の金額 (価格とコスト) | | | `charges.metadata.[total_tax]` | 文字列 | この取引 (支払い) に係る税金の合計 | | 次のコードスニペットの例では、対象となるデスティネーション支払いに移動し、スキーマごとに更新する方法を示しています。 1. 取引からデスティネーション支払いまで追跡します #### JavaScript ```jsx 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 とメタデータで支払いを更新します。データの受け渡しやアプリの同期を行うには、顧客はプラットフォームではなく、連結アカウントに属している必要があります。 #### JavaScript ```jsx const customer = await StripeClient.customers.create( { email: `jenny.rosen@example.com`, name: "Jenny Rosen", address: { city: "Brothers", state: "Oregon", country: "USA", line1: "27 Fredrick Ave", 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 に保存されている支払い、顧客、商品のすべてのデータにアクセスできます。以下のメタデータスキーマを使用して、任意のプラットフォームデータをアプリに渡すことができます。 | フィールドまたはキーの名前 | 形式 (標準の CSV ルールを適用) | 説明 | | ------------------------------------------- | ------------------- | ------------------------------------------------------------------ | | `customer.metadata.[platform_customer_ID]` | 文字列 | プラットフォームのシステムに記録されている顧客 ID | | `payment.metadata.[platform_product_ID]` | 文字列、CSV の複数製品 | このトランザクションに関連してプラットフォームのシステムに記録されている製品 ID (Stripe 製品 ID と異なる場合) | | `payment.metadata.[platform_product_name]` | 文字列、CSV の複数製品 | このトランザクションに関連してプラットフォームのシステムに記録されている製品名またはサービス名 (Stripe 製品名と異なる場合) | | `payment.metadata.[platform_product_value]` | 文字列、CSV の複数製品 | ID および名前の配列に対応する個々の製品の金額 (価格またはコスト) (Stripe 製品の金額と異なる場合) | | `payment.metadata.[platform_order_ID]` | 文字列 | このトランザクションに関連してプラットフォームのシステムに記録されている注文 ID (支払い) | | `payment.metadata.[platform_charge_ID]` | 文字列 | プラットフォームに記録され、ユーザーに表示される支払いまたは取引の ID (Stripe 決済 ID と異なる場合) |