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

注

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

Connect の埋め込みコンポーネントの使用を開始する

ダッシュボードの機能をウェブサイトに埋め込む方法をご紹介します。

ページをコピー

Connect の埋め込みコンポーネントを使用して、連結アカウントのダッシュボード機能をウェブサイトに追加します。これらのライブラリとサポートする API を使用することで、ダッシュボードから Stripe 製品に直接アクセスできる許可をユーザーに付与できます。

より実践的なガイドについては、Connect の埋め込みコンポーネント導入のクイックスタートをご覧ください。こちらからサンプルの実装をダウンロードすることもできます。Connect の埋め込みコンポーネントのデザインをカスタマイズするには、StripeConnectInstance を初期化する際に appearance オプションを使用します。デザインパラメーターの全リストをご覧ください。

Connect.js を初期化する
クライアント側
サーバー側

Stripe は AccountSession を使用して、API アクセスを連結アカウントに委任する意図を表します。

AccountSessions API は Client Secret を返し、ウェブクライアントの埋め込みコンポーネントが、まるでユーザーが API コールを行っているかのように連結アカウントのリソースにアクセスできるようにします。

AccountSession を作成する サーバー

1 ページのアプリケーションでは、クライアントがサーバーへのリクエストを開始して、アカウントセッションを取得します。client secret をブラウザーに返す新しいエンドポイントを、サーバー側で作成できます。

main.rb
require 'sinatra'
require 'stripe'
# This is a placeholder - it should be replaced with your secret API key.
# Sign in to see your own test API key embedded in code samples.
# Don’t submit any personally identifiable information in requests made with this key.
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


post '/account_session' do
  content_type 'application/json'

  # Create an AccountSession
  begin
    account_session = Stripe::AccountSession.create({
      account: 
'{{CONNECTED_ACCOUNT_ID}}'
,
      components: {
        payments: {
          enabled: true,
          features: {
            refund_management: true,
            dispute_management: true,
            capture_payments: true
          }
        }
      }
    })

    {
      client_secret: account_session[:client_secret]
    }.to_json
  rescue => error
    puts "An error occurred when calling the Stripe API to create an account session: #{error.message}";
    return [500, { error: error.message }.to_json]
  end
end

Create Account Session API

The Create Account Session API determines component and feature access for Connect embedded components. Stripe enforces these parameters for any components that correspond to the account session. If your site supports multiple user roles, make sure components and features that are enabled for that account session correspond to the current user’s role. For example, you can enable refund management only for administrators of your site, but not for other users. To make sure user role access are enforced, you must map your site’s user role to account session components.

Connect.js を設定する クライアント

We recommend setting up Connect.js with npm as shown in the following example, but it’s also possible without npm.

npm パッケージをインストールして、Connect.js をモジュールとして使用します。

Command Line
npm install --save @stripe/connect-js

Connect.js を読み込み初期化する クライアント

公開可能キーと、サーバー上に作成した新しいエンドポイントを呼び出してクライアントシークレットを取得する機能を指定して、loadConnectAndInitialize を呼び出します。返された StripeConnectInstance を使用して、埋め込みコンポーネントを作成します。Connect.js を初期化すると、DOM に対してコンポーネントのマウントとマウント解除をいつでも行うことができます。これは React や Vue ポータル内で表示されるすべての要素に適用できます。

コンポーネントを作成するには、上記で作成した StripeConnectInstance で create を呼び出します。これにより、Connect.js が登録して DOM を自動的に Stripe に接続するために使用するカスタム要素が作成されます。その後、この要素を DOM に append できます。

payments を指定して create を呼び出したら、結果を DOM に追加して、決済 UI を表示します。

index.html
<head>
  <script type="module" src="index.js" defer></script>
</head>
<body>
  <h1>Payments</h1>
  <div id="container"></div>
  <div id="error" hidden>Something went wrong!</div>
</body>
index.js
import {loadConnectAndInitialize} from '@stripe/connect-js';

const fetchClientSecret = async () => {
  // Fetch the AccountSession client secret
  const response = await fetch('/account_session', { method: "POST" });
  if (!response.ok) {
    // Handle errors on the client side here
    const {error} = await response.json();
    console.error('An error occurred: ', error);
    document.querySelector('#error').removeAttribute('hidden');
    return undefined;
  } else {
    const {client_secret: clientSecret} = await response.json();
    document.querySelector('#error').setAttribute('hidden', '');
    return clientSecret;
  }
}

const stripeConnectInstance = loadConnectAndInitialize({
    // This is a placeholder - it should be replaced with your publishable API key.
    // Sign in to see your own test API key embedded in code samples.
    // Don’t submit any personally identifiable information in requests made with this key.
    publishableKey: 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
,
    fetchClientSecret: fetchClientSecret,
  });
const paymentComponent = stripeConnectInstance.create("payments");
const container = document.getElementById("container");
container.appendChild(paymentComponent);

サポートされている埋め込みコンポーネントの一覧を参照 →

Configure Connect.js
クライアント側

クライアントの loadConnectAndInitialize メソッドは、Connect.js を設定するさまざまなオプションを受け取ります。

オプション説明
publishableKey構築しているシステムの公開可能キー。必須
fetchClientSecretThe function that retrieves the client secret returned by /v1/account_sessions. This tells StripeConnectInstance which account to delegate access to. This function is also used to retrieve a client secret function to refresh the session when it expires. fetchClientSecret should always create a new account session and return a fresh client_secret.必須
appearanceConnect 埋め込みコンポーネントのデザインをカスタマイズするオブジェクト。オプション
localeConnect 埋め込みコンポーネントが使用するロケールを指定するパラメーター。ロケールのデフォルトはブラウザーの言語です。指定されたロケールが直接は対応していない場合は、妥当な代替言語を使用します (たとえば、fr-be は fr-fr に戻る可能性があります)。サポートされているロケールのリストについては、各地域への適応を参照してください。オプション
fontsStripeConnectInstance から作成された埋め込みコンポーネントで使用できるカスタムフォントの配列。フォントは、CssFontSource または CustomFontSource オブジェクトとして指定できます。オプション

Connect 埋め込みコンポーネントのデザインをカスタマイズする

埋め込みコンポーネント Figma UI ツールキットには、すべてのコンポーネント、一般的なパターン、サンプルアプリケーションが含まれています。これを使用して、ウェブサイトに埋め込まれた UI を可視化してデザインできます。

Stripe は、Connect 埋め込みコンポーネントのデザインをカスタマイズするための一連のオプションを提供しています。これらをカスタマイズすると、デザインシステムのボタン、アイコン、その他のアクセントに影響します。

Necessary popups

Some behavior in embedded components, such as user authentication, must be presented in a popup. You can’t customize the embedded component to eliminate such popups.

これらのオプションは、StripeConnectInstance の初期化時に、Appearance を appearance オブジェクトに渡すことで設定できます。Connect 埋め込みコンポーネントのスタイルを変更するのに使用できるのは、Connect.js のオプションのみです。Connect 埋め込みコンポーネントのフォントファミリーと背景色は CSS セレクターで上書きできますが、Stripe はそれ以外のスタイルの上書きをサポートしていません。

index.js
const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
,
  fetchClientSecret: fetchClientSecret,
  fonts: [
    {
      cssSrc: "https://myfonts.example.com/mycssfile.css",
    },
    {
      src: `url(https://my-domain.com/assets/my-font-2.woff)`,
      family: 'My Font'
    }
  ],
  appearance: {
    // See all possible variables below
    overlays: "dialog",
    variables: {
      fontFamily: 'My Font',
      colorPrimary: "#FF0000",
    },
  },
});

fonts オブジェクト

stripeConnect.initialize の fonts オブジェクトは、CssFontSource または CustomFontSource オブジェクトの配列を受け取ります。

ページでカスタムフォント (.woff ファイルや .tff ファイルなど) を使用する場合は、Connect 埋め込みコンポーネントの初期化時にフォントファイルを指定する必要があります。これにより、Connect 埋め込みコンポーネントでフォントを適切にレンダリングできます。ファイルは次のように指定できます。

CssFontSource

StripeConnectInstance の作成時にカスタムフォントを定義するスタイルシートの URL を渡すには、このオブジェクトを使用します。CssFontSource オブジェクトでは、CSP 設定 で、CssFontSource として指定された CSS ファイルの URL に関連付けられたドメインの取得を許可する必要があります。

名前
タイプ
値の例
cssSrc
文字列 required
https://fonts.googleapis.com/css?family=Open+Sans
@font-face 定義を持つ CSS ファイルを指す相対 URL または絶対 URL。ファイルは https でホストされている必要があります。コンテンツセキュリティポリシー(CSP) を使用する場合、ファイルに追加のディレクティブが必要になることがあります。

CustomFontSource

StripeConnectInstance の作成時にカスタムフォントを渡すには、このオブジェクトを使用します。

名前
タイプ
値の例
family
文字列 required
Avenir
フォントに付ける名前。
src
文字列 required
url(https://my-domain.com/assets/avenir.woff)
カスタムフォントファイルを指す有効な src 値。これは (必ずではありませんが) 通常は .woff、.otf、または .svg というサフィックスが付いたファイルへのリンクです。ファイルは https でホストされている必要があります。
display
文字列 optional
auto
有効な font-display 値。
style
文字列 optional
normal
normal、italic、oblique のいずれか。
unicodeRange
文字列 optional
U+0-7F
有効な unicode-range 値。
weight
文字列 optional
400
有効な font-weight。これは文字列であり、数値ではありません。

appearance オブジェクト

loadConnectAndInitialize の appearance オブジェクトには、次のオプションのプロパティがあります。

名前
タイプ
値の例
overlays
‘dialog’ (デフォルト) | ‘drawer’
dialog
Connect.js デザインシステム全体で使用されるオーバーレイのタイプ。これを Dialog または Drawer に設定します。
variables
オブジェクト
{colorPrimary: "#0074D4"}
デザイン変数の一覧を参照してください。

Update Connect embedded components after initialization

update メソッドは、初期化後の Connect 埋め込みコンポーネントの更新に対応しています。これを使用して、実行時に (ページを更新せずに) デザインオプションを切り替えることができます。これを行うには、initialize で作成したのと同じ stripeConnectInstance オブジェクトを使用し、そのオブジェクトに対して update メソッドを呼び出します。

index.js
stripeConnectInstance.update({
  appearance: {
    variables: {
      colorPrimary: "#FF0000",
    },
  },
  locale: 'en-US',
});

注

すべてのオプション (fonts など) を更新できるわけではありません。このメソッドで対応しているオプションは、initialize で提供されているオプションのサブセットです。そうすることによって、appearance と locale の更新に対応しています。

幅と高さ

Connect 埋め込みコンポーネントは、通常の block HTML 要素と同様に動作します。デフォルトでは、親 HTML 要素の width の 100% に設定し、内部にレンダリングされるコンテンツに応じて高さを大きくします。HTML の親の width を指定することで、Connect 埋め込みコンポーネントの width を制御できます。height はレンダリングされるコンテンツによって変わるため、直接制御することはできませんが、他の HTML block 要素と同じように、maxHeight と overflow: scroll で高さを制限できます。

認証

Stripe は、Connect 埋め込みコンポーネントでアカウントセッションとユーザー認証情報を管理するための一連の API を提供しています。

Client Secret を更新する

長時間実行されるセッションでは、最初に提供された Client Secret によるセッションが期限切れになることがあります。有効期限が切れると、Stripe は自動的に fetchClientSecret を使用して新しい Client Secret を取得し、セッションを更新します。貴社が追加のパラメーターを渡す必要はありません。

index.js
import { loadConnectAndInitialize } from "@stripe/connect-js";
// Example method to retrieve the client secret from your server
const fetchClientSecret = async () => {
  const response = await fetch('/account_session', { method: "POST" });
  const {client_secret: clientSecret} = await response.json();
  return clientSecret;
}

const stripeConnectInstance = loadConnectAndInitialize({
  publishableKey: "{{PUBLISHABLE_KEY}}",
  fetchClientSecret: fetchClientSecret,
});

ログアウトする

ユーザーがアプリからログアウトした後に、stripeConnectInstance で logout を呼び出して、関連するアカウントセッションオブジェクトを破棄することをお勧めします。そうすることで、その stripeConnectInstance に関連付けられているすべての Connect 埋め込みコンポーネントが無効になります。

index.js
// Call this when your user logs out
stripeConnectInstance.logout();

CSP と HTTP ヘッダーの要件

ウェブサイトにコンテンツセキュリティポリシーを導入している場合は、次のルールを追加してポリシーを更新する必要があります。

  • frame-src https://connect-js.stripe.com https://js.stripe.com
  • img-src https://*.stripe.com
  • script-src https://connect-js.stripe.com https://js.stripe.com
  • style-src sha256-0hAheEzaMe6uXIKV4EehS9pu1am1lj/KnnzrOYqckXk= (空のスタイル要素の SHA)

CSS ファイルを使用して Connect の埋め込みコンポーネントで使用するウェブフォントを読み込む場合は、その URL がお客様の connect-src CSP ディレクティブで許可されている必要があります。

特定の HTTP レスポンスヘッダーを設定すると、Connect 埋め込みコンポーネントの全機能が有効になります。

  • Cross-Origin-Opener-Policy: unsafe-none。これ (unsafe-none) はヘッダーのデフォルト値であるため、このヘッダーを設定しなくても機能します。same-origin など他の値を設定すると、Connect 埋め込みコンポーネントのユーザー認証が機能しなくなります。

サポートされているブラウザー

We support the same set of browsers that the Stripe Dashboard currently supports:

  • Chrome と Firefox の最新の 20 個のメジャーバージョン
  • Safari と Edge の最新の 2 つのメジャーバージョン
  • iOS モバイル Safari の最新の 2 つのメジャーバージョン

Connect 埋め込みコンポーネントはウェブブラウザーにのみ対応しており、モバイルアプリケーションやデスクトップアプリケーションの中の埋め込みウェブビューでは使用できません。

各地域への適応

Connect.js を初期化するときに、locale パラメーターを渡すことができます。埋め込みコンポーネントのロケールをウェブサイトのロケールに合わせるには、ウェブサイトでレンダリングする UI のロケールを locale パラメーターに渡します。

locale パラメーターのデフォルト値は、ブラウザーに設定されているロケールによって決まります。指定されたロケールが直接は対応していない場合は、妥当な代替言語が使用されます (たとえば、fr-be は fr-fr に戻る可能性があります)。

Connect 埋め込みコンポーネントは、次のロケールに対応しています。

言語ロケールコード
ブルガリア語 (ブルガリア)bg-BG
中国語 (簡体字)zh-Hans
中国語 (繁体字 - 香港)zh-Hant-HK
中国語 (繁体字 - 台湾)zh-Hant-TW
クロアチア語 (クロアチア)hr-HR
チェコ語 (チェコ)cs-CZ
デンマーク語 (デンマーク)da-DK
オランダ語 (オランダ)nl-NL
英語 (オーストラリア)en-AU
英語 (インド)en-IN
英語 (アイルランド)en-IE
英語 (ニュージーランド)en-NZ
英語 (シンガポール)en-SG
英語 (イギリス)en-GB
英語 (アメリカ)en-US
エストニア語 (エストニア)et-EE
フィリピノ語 (フィリピン)fil-PH
フィンランド語 (フィンランド)fi-FI
フランス語 (カナダ)fr-CA
フランス語 (フランス)fr-FR
ドイツ語 (ドイツ)de-DE
ギリシャ語 (ギリシャ)el-GR
ハンガリー語 (ハンガリー)hu-HU
インドネシア語 (インドネシア)id-ID
イタリア語 (イタリア)it-IT
日本語 (日本)ja-JP
韓国語 (韓国)ko-KR
ラトビア語 (ラトビア)lv-LV
リトアニア語 (リトアニア)lt-LT
マレー語 (マレーシア)ms-MY
マルタ語 (マルタ)mt-MT
ノルウェーブークモール語 (ノルウェー)nb-NO
ポーランド語 (ポーランド)pl-PL
ポルトガル語 (ブラジル)pt-BR
ポルトガル語 (ポルトガル)pt-PT
ルーマニア語 (ルーマニア)ro-RO
スロバキア語 (スロバキア)sk-SK
スロベニア語 (スロベニア)sl-SI
スペイン語 (アルゼンチン)es-AR
スペイン語 (ブラジル)es-BR
スペイン語 (中南米)es-419
スペイン語 (メキシコ)es-MX
スペイン語 (スペイン)es-ES
スウェーデン語 (スウェーデン)sv-SE
タイ語 (タイ)th-TH
トルコ語 (トルコ)tr-TR
ベトナム語 (ベトナム)vi-VN

読み込みエラーを処理する

コンポーネントの読み込みに失敗した場合、埋め込みコンポーネントに読み込みエラーハンドラを指定することで、失敗に対応できます。失敗の原因に応じて、読み込みエラーハンドラは複数回呼び出されます。読み込みエラーハンドラによってトリガーされるロジックは、べき等でなければなりません。

index.js
// Load errors are emitted by all components. We use Balances as an example here.
const balances = stripeConnectInstance.create('balances');
balances.setOnLoadError((loadError) => {
  const componentName = loadError.elementTagName
  const error = loadError.error

  console.log(componentName + " failed to load")
  console.log(`${error.type}: ${error.message}`);
});

container.appendChild(balances);
MethodDescriptionVariables
setOnLoadErrorThe component executes this callback function when a load failure occurs.
  • loadError.error: See the load error object
  • loadError.elementTagName: The name of HTML tag used to render the component in the browser

The load error object

Every time there’s a load failure, an error object is passed to the load error handler with the following properties.

Name
Type
Example value
type
See types of load failures
authentication_error
The type of error
message
string | undefined
Failed to fetch account session
Further description about the error

Types of load failures

When a component fails to load, we detect the type of failure and map it to one of the types below. If the load error type can’t be determined it is marked as an api_error.

TypeDescription
api_connection_errorFailure to connect to Stripe’s API
authentication_errorFailure to perform the authentication flow within Connect embedded components
account_session_create_errorAccount session creation failed
invalid_request_errorRequest failed with an 4xx status code, typically caused by platform configuration issues
rate_limit_errorRequest failed because an abnormal request rate was detected
api_errorAPI errors covering any other type of problem, such as a temporary problem with Stripe’s servers

埋め込みコンポーネントの表示を検出する

コンポーネントが作成された後は、コンポーネントの Javascript がブラウザーに読み込まれ、解析されるまで、UI はユーザーに表示されません。これにより、コンポーネントが読み込みの完了後にポップアップ表示される場合があります。これを回避するには、コンポーネントが作成される前に独自の読み込み UI を表示し、コンポーネントが表示された後に UI を非表示にします。埋め込みコンポーネントはすべて、ユーザーに UI が表示される直前に呼び出されるコールバック関数を受け入れることができます。

index.html
<span id="spinner"></span>
<div id="balances-container"></div>
index.js
// Loader start events are emitted by all components. We use Balances as an example here.
const container = document.getElementById('balances-container');
const balances = stripeConnectInstance.create('balances');

balances.setOnLoaderStart((event) => {
  container.getElementById("spinner").display = "none";
  console.log(`${event.elementTagName} is visible to users`)
});

container.appendChild(balances);
MethodDescriptionVariables
setOnLoaderStartThe component executes this callback function before any UI is displayed to the user.
  • event.elementTagName: The name of HTML tag used to render the component in the browser

npm を使用せずに Connect.js を使用する

Stripe の javascript と React コンポーネントのラッパーを導入することをお勧めします。これにより、Connect の埋め込みコンポーネントを簡単に読み込み、当社がサポートするインターフェイスの TypeScript 定義を得ることができます。貴社のビルドシステムが現在、パッケージへの依存をサポートしていない場合、このパッケージなしで導入することができます。

自社サイトの各ページの <head> に、Connect.js スクリプトタグを手動で追加します。

<!-- Somewhere in your site's <head> -->
<script src="https://connect-js.stripe.com/v1.0/connect.js" async></script>

Connect.js は読み込みが完了すると、グローバルウィンドウ変数 StripeConnect を初期化し、定義されている場合は StripeConnect.onLoad を呼び出します。onload 関数を設定し、loadConnectAndInitialize と同じ Connect.js オプションを指定して StripeConnect.init を呼び出すことで、Connect.js を安全に初期化できます。loadConnectAndInitialize によって返されるインスタンスを使用する方法と同じように、init によって返される Connect インスタンスを使用して、HTML + JS の実装で埋め込みコンポーネントを作成できます。

index.js
window.StripeConnect = window.StripeConnect || {};
StripeConnect.onLoad = () => {
  const stripeConnectInstance = StripeConnect.init({
      // This is a placeholder - it should be replaced with your publishable API key.
      // Sign in to see your own test API key embedded in code samples.
      // Don’t submit any personally identifiable information in requests made with this key.
      publishableKey: 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
,
      fetchClientSecret: fetchClientSecret,
    });

  const payments = stripeConnectInstance.create('payments');
  document.body.appendChild(payments);
};

Connect の埋め込みコンポーネントでのユーザー認証

Connect の埋め込みコンポーネントでは通常、ユーザー認証を必要としません。場合によっては、Connect の埋め込みコンポーネントでは、必要な機能 (アカウント登録コンポーネントで、アカウントの法人情報を記述するなど) を提供するために、連結アカウントが Stripe アカウントでサインインする必要があります。

認証には、Stripe が所有するウィンドウへのポップアップが含まれます。連結アカウントは、ワークフローを続行する前に認証する必要があります。

以下のコンポーネントは、特定のシナリオで連結アカウントにより認証される必要があります。

他のコンポーネントでは、最初にレンダリングされた後にコンポーネント内での認証が必要になることがあります。これらのコンポーネントとシナリオの認証は、要件が変更されたときに Stripe が更新情報を収集する責任を負う、連結アカウントに必要です。要件が期限に達したか変更された場合に、更新情報を収集する責任を負う連結アカウントの場合、Stripe 認証は、disable_stripe_user_authentication アカウントセッション機能によって制御されます。ベストプラクティスとして、2 段階認証または同等のセキュリティ対策を導入することをお勧めします。Custom など、この機能をサポートするアカウント設定では、連結アカウントがマイナス残高を返済できない場合、お客様は連結アカウントの責任を負うものとします。

パフォーマンスのベストプラクティス

Connect 埋め込みコンポーネントの読み込み時間をできるだけ短くしたい場合は、次の推奨事項をお試しください。

  • connect.js スクリプトをできるだけ早くフローに読み込みます。HTML の head にこのスクリプトを含めることで、スクリプトをすぐに読み込ませることができます。npm パッケージ SDK のデフォルトの動作を応用することもできます。この場合、ページの Javascript が読み込まれたときにスクリプトの読み込みが開始します。
  • フローの初期の段階で loadConnectAndInitialize を呼び出します。
  • 単一の接続インスタンスを作成する:セッションごとに 1 回だけ loadConnectAndInitialize を呼び出して、単一の接続インスタンスを作成します。その後、そのインスタンスを再利用して、複数のコンポーネントを作成・管理することができます。このとき、コンポーネントごとに単一の接続インスタンスを作成したり、セッションごとに複数の接続インスタンスを作成したりするミスがよく起こります。その結果、余分なリソース消費と API リクエストが発生します。React を使用している場合は、状態管理ライブラリまたは React コンテキストを使用してこのインスタンスを管理できます。
  • 適切な SDK を使用する:connect-js または react-connect-js npm パッケージ SDK を使用します。これらの SDK は、埋め込みコンポーネントを初期化してパフォーマンスの最大化を図ります。
このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc