# 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 "<<YOUR_SECRET_KEY>>:" \
  -H "Stripe-Version: 2026-09-30.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)のリストをご覧ください。 |

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

#### HTML と JavaScript

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

```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<String, String>` | アプリが使用する、プラットフォームに関するデータを設定します。 |

#### React

| React プロパティ | タイプ | 説明 |
| --- | --- | --- |
| `app` | `string` | 連結アカウントがレンダリングできるアプリの ID。詳しくは、[利用可能なアプリ](https://docs.stripe.com/stripe-apps/embedded-apps.md#app-select)をご覧ください。 |
| `appData` | `Record<String, String>` | アプリが使用する、プラットフォームに関するデータ。 |

## 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. 取引からデスティネーション支払いまで追跡します

#### TypeScript

```ts
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 と異なる場合) |

### アプリ用の埋め込みコンポーネントのベータ版をご希望の場合

Enter your email to request access.

```bash
curl https://docs.stripe.com/preview/register \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Referer: https://docs.stripe.com/stripe-apps/embedded-apps" \
  -d '{"email": "EMAIL", "preview": "stripe_apps_for_platforms_preview"}'
```