# カスタマーポータルのディープリンク カスタマーポータルの API を使用して、効率的な顧客フローを設計します。 [カスタマーポータル](https://docs.stripe.com/customer-management.md)を使用すれば、自分で構築することなく、サブスクリプションや決済手段の管理を顧客に提供できます。顧客の対応を効率化し、自社アプリと Stripe 間のワークフローをさらにカスタマイズしたい場合は、カスタマーポータル[フロー](https://docs.stripe.com/api/customer_portal/sessions/object.md#portal_session_object-flow)を作成できます。 ## カスタマーポータルのフロー 「フロー」は、カスタマーポータルへのカスタマイズ可能なディープリンクです。ポータルフローでは以下を行うことができます。 1. 顧客に実行を求める指定アクションが表示されるページにディープリンクで直接接続します。カスタマーポータルの他の部分にアクセスするナビゲーションコンポーネントは非表示になるため、顧客は 1 つのアクションに注目できます。 2. 顧客がアクションを完了した後のリダイレクトの動作をカスタマイズします。お客様独自の URL、オンラインの確認ページ、またはポータルのホームページに即時にリダイレクトします。 3. 事前入力されたプロモーションコードやカスタムメッセージなどの独自のオプションによって、フローをカスタマイズします。 ### フローのタイプ フローの [type](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data-type) は、顧客がどの個別フローまたはアクションを実行するかを定義します。以下は、現在利用可能なフローのタイプです。 | フロータイプ | 説明 | 例 | | --- | --- | --- | | `payment_method_update` | 顧客が新しい支払い方法を追加できるようにするには、`payment_method_update` を使用します。支払い方法は、`customer.invoice_settings.default_payment_method` として設定されます。 | ![支払い方法の更新フローの例](https://b.stripecdn.com/docs-statics-srv/assets/payment_method_update.6f92b4642ce28020952f263360c83014.png) 支払い方法の更新フロー | | `subscription_cancel` | 顧客が特定のサブスクリプションをキャンセルできるようにするには、`subscription_cancel` を使用します。 [API](https://docs.stripe.com/api/customer_portal/configurations/object.md#portal_configuration_object-features-subscription_cancel-mode) や[ダッシュボード](https://dashboard.stripe.com/test/settings/billing/portal)を通じてポータル設定を更新することで、サブスクリプションが即時にキャンセルされるか、期間終了時にキャンセルするかをカスタマイズできます。 | ![サブスクリプションのキャンセルフローの例](https://b.stripecdn.com/docs-statics-srv/assets/subscription_cancel.6943958d0358b97241a1f4d2703d3bfb.png) サブスクリプションのキャンセルフロー | | `subscription_update` | 別のプランへのアップグレードやダウングレード、現在のプランの数量の更新など、別の更新オプションを顧客が選択できるようにするには、`subscription_update` を使用します。 [API](https://docs.stripe.com/api/customer_portal/configurations/object.md#portal_configuration_object-features-subscription_update-products) または[ダッシュボード](https://dashboard.stripe.com/test/settings/billing/portal)を通じてポータル設定を更新することで、利用可能なプランをカスタマイズできます。 | ![サブスクリプションの更新フローの例](https://b.stripecdn.com/docs-statics-srv/assets/subscription_update.8426206cdf98ba10d04680b782644b67.png) サブスクリプションプラン更新フロー | | `subscription_update_confirm` | 顧客がサブスクリプションへの更新の明細を確定できるようにするには、`subscription_update_confirm` を使用します。 このオプションは、独自の料金ページがあるが、更新情報を表示する処理 (次回の請求書や日割り計算などの更新情報の表示、支払い失敗の処理、[3D セキュア認証](https://docs.stripe.com/payments/3d-secure.md)の処理など) をオフロードしたい場合に使用できます。 サブスクリプション更新に適用するクーポンやプロモーションコードも指定できます。これは、別のプランへの切り替えに対して割引を提供するプロモーションキャンペーンなどで使用できます。 | ![サブスクリプション更新の確認フローの例](https://b.stripecdn.com/docs-statics-srv/assets/subscription_update_confirm.5a06b658cc8a15971fdfae54fc7708da.png) サブスクリプション更新・確認フロー | | `customer_update` | `customer_update` を使用して、顧客が請求先住所や納税者番号などの請求先情報を更新できるようにします。 | ![顧客更新フローの例](https://b.stripecdn.com/docs-statics-srv/assets/customer_update.8054b16520ab6e1052b23c6c2d4d8508.png) 顧客更新フロー | ## フローを作成する カスタマーポータルフローは、[Customer Portal API](https://docs.stripe.com/api/customer_portal/sessions/create.md) の拡張機能です。このガイドを使用する前に、一般ガイドに従って [API とカスタマーポータルを連携](https://docs.stripe.com/customer-management/integrate-customer-portal.md)してください。 フローを作成するには、ポータルセッションの作成時に [flow_data](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data) を指定します。 顧客に実行を求めるフローの[タイプ](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data-type)を設定します。フローの `type` によっては、サブスクリプション ID などの追加のデータを渡すことが必要になる場合があります。 以下は、各フロータイプの設定方法の例です。 > #### Accounts v2 API を使用した顧客の表現 > > Accounts v2 API では、Connect ユーザーには一般提供され、その他の Stripe ユーザーには公開プレビューで提供されます。Accounts v2 プレビューの一部である場合は、コードで[プレビューバージョン](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning)を指定する必要があります。 > > Accounts v2 のプレビューに参加するには、ダッシュボードの [Account previews and features](https://dashboard.stripe.com/settings/previews) に移動して、**Global Payouts の再利用可能な決済手段**を有効にします。 > > ほとんどのユースケースでは、[Customer](https://docs.stripe.com/api/customers.md) オブジェクトを使用するのではなく、[顧客を顧客設定済みの Account オブジェクトとしてモデル化する](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md)ことをお勧めします。 #### Accounts v2 #### 決済手段の更新 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=payment_method_update" ``` #### サブスクリプションのキャンセル キャンセルする `subscription` を `subscription_cancel[subscription]` に渡します。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_cancel" \ -d "flow_data[subscription_cancel][subscription]={{SUBSCRIPTION_ID}}" ``` #### サブスクリプションの更新 更新する `subscription` を `subscription_update[subscription]` に渡します。[ポータルの設定を行う](https://docs.stripe.com/customer-management/integrate-customer-portal.md#configure) を使用して、可能な更新オプションとしてページに表示する商品と価格を設定します。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_update" \ -d "flow_data[subscription_update][subscription]={{SUBSCRIPTION_ID}}" ``` #### サブスクリプションの更新の確認 更新する `subscription` を `subscription_update_confirm[subscription]` に渡します。また、`items` の配列を `subscription_update_confirm[items]` に渡すことで、サブスクリプションのアイテムの更新対象を指定する必要もあります。 まず、現在のサブスクリプションの `items` を取得します。そのためには、`subscription` オブジェクトを取得し、[items.data](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-items-data) を確認します。次に、更新するサブスクリプションアイテムの `id` を取得して、それを `subscription_update_confirm[items]` 配列に渡します。その後、顧客が確定できるように、項目に新しい `price` または `quantity` を指定できます。 現在、指定できる項目は 1 つのみで、複数の項目があるサブスクリプションは更新できません。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_update_confirm" \ -d "flow_data[subscription_update_confirm][subscription]={{SUBSCRIPTION_ID}}" \ -d "flow_data[subscription_update_confirm][items][0][id]={{SUBSCRIPTIONITEM_ID}}" \ -d "flow_data[subscription_update_confirm][items][0][quantity]=1" \ -d "flow_data[subscription_update_confirm][items][0][price]={{PRICE_ID}}" \ -d "flow_data[subscription_update_confirm][discounts][0][coupon]={{COUPON_ID}}" ``` #### 顧客の更新 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=customer_update" ``` #### Customers v1 #### 決済手段の更新 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=payment_method_update" ``` #### サブスクリプションのキャンセル キャンセルする `subscription` を `subscription_cancel[subscription]` に渡します。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_cancel" \ -d "flow_data[subscription_cancel][subscription]={{SUBSCRIPTION_ID}}" ``` #### サブスクリプションの更新 更新する `subscription` を `subscription_update[subscription]` に渡します。[ポータルの設定を行う](https://docs.stripe.com/customer-management/integrate-customer-portal.md#configure) を使用して、可能な更新オプションとしてページに表示する商品と価格を設定します。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_update" \ -d "flow_data[subscription_update][subscription]={{SUBSCRIPTION_ID}}" ``` #### サブスクリプションの更新の確認 更新する `subscription` を `subscription_update_confirm[subscription]` に渡します。また、`items` の配列を `subscription_update_confirm[items]` に渡すことで、サブスクリプションのアイテムの更新対象を指定する必要もあります。 まず、現在のサブスクリプションの `items` を取得します。そのためには、`subscription` オブジェクトを取得し、[items.data](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-items-data) を確認します。次に、更新するサブスクリプションアイテムの `id` を取得して、それを `subscription_update_confirm[items]` 配列に渡します。その後、顧客が確定できるように、項目に新しい `price` または `quantity` を指定できます。 現在、指定できる項目は 1 つのみで、複数の項目があるサブスクリプションは更新できません。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_update_confirm" \ -d "flow_data[subscription_update_confirm][subscription]={{SUBSCRIPTION_ID}}" \ -d "flow_data[subscription_update_confirm][items][0][id]={{SUBSCRIPTIONITEM_ID}}" \ -d "flow_data[subscription_update_confirm][items][0][quantity]=1" \ -d "flow_data[subscription_update_confirm][items][0][price]={{PRICE_ID}}" \ -d "flow_data[subscription_update_confirm][discounts][0][coupon]={{COUPON_ID}}" ``` #### 顧客の更新 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=customer_update" ``` レスポンスのポータルセッションの `url` が、作成したフローにディープリンクで接続されます。この URL を使用して、サイトからポータルフローに顧客をリダイレクトします。 ## 完了後の動作をカスタマイズする 顧客がフローを正常に完了すると、完了した更新の詳細を示すローカライズ版の確認ページが表示されます。このページの確認メッセージをカスタマイズしたり、選択した URL やアカウント情報がすべて表示されるカスタマーポータルのホームページにリダイレクトしたりすることができます。 この動作をカスタマイズするには、`flow_data` に [after_completion](https://docs.stripe.com/api/customer_portal/sessions/create.md#create_portal_session-flow_data-after_completion) を設定します。 以下の例では、顧客がサブスクリプションをキャンセルし、その後お客様のサイトにリダイレクトされます。 #### Accounts v2 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_cancel" \ -d "flow_data[subscription_cancel][subscription]={{SUBSCRIPTION_ID}}" \ -d "flow_data[after_completion][type]=redirect" \ --data-urlencode "flow_data[after_completion][redirect][return_url]=https://example.com/account/subscription_canceled" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ --data-urlencode "return_url=https://example.com/account/overview" \ -d "flow_data[type]=subscription_cancel" \ -d "flow_data[subscription_cancel][subscription]={{SUBSCRIPTION_ID}}" \ -d "flow_data[after_completion][type]=redirect" \ --data-urlencode "flow_data[after_completion][redirect][return_url]=https://example.com/account/subscription_canceled" ``` 上位の `return_url` は、顧客がいつでもクリックしてウェブサイトに戻ることができるリンクです (たとえば、キャンセルしないことにした場合など)。`flow_data[after_completion][redirect][return_url]` は、顧客がサブスクリプションを正常にキャンセルした後にウェブサイトに戻るためのリンクです。