# API でカスタマーポータルを実装する Stripe API を使用してカスタマーポータルを実装する方法をご紹介します。 導入で [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer) を使用している場合は、コード例内の `Customer` とイベント参照を、対応する Accounts v2 API リファレンスに置き換えてください。詳細については、[Account オブジェクトで顧客を表す](https://docs.stripe.com/connect/use-accounts-as-customers.md)をご覧ください。 カスタマーポータルを使用すれば、構築を自身で行わなくても顧客がサブスクリプション、請求書、請求書を管理できるようにすることができます。ポータルの設定と導入を終えると、顧客は提携ブランドのダッシュボードにリダイレクトされます。そこで、顧客は設定された機能に基づいて各自のアカウントを管理できます。 アプリケーションをカスタマーポータルに組み込むには、以下の手順に従います。 1. ポータルの機能とユーザーインターフェイス (UI) を[設定](https://docs.stripe.com/customer-management/integrate-customer-portal.md#configure)します。これはダッシュボードで実行できます。 1. [リダイレクトを実装](https://docs.stripe.com/customer-management/integrate-customer-portal.md#redirect)してアプリケーションにポータルを導入します。 1. [Webhook をリッスン](https://docs.stripe.com/customer-management/integrate-customer-portal.md#webhooks)して顧客のサブスクリプションと支払い方法の更新を受け取ります。 1. 本番環境でのポータルの[利用を開始](https://docs.stripe.com/customer-management/integrate-customer-portal.md#go-live)します。 必要に応じて、ポータルセッションを[カスタマイズ](https://docs.stripe.com/customer-management/integrate-customer-portal.md#customize)し、顧客ごとに異なる機能を有効にできます。 ## ポータルを設定 まず、[Stripe アカウントを登録](https://dashboard.stripe.com/register/)する必要があります。 カスタマーポータルを実装する前に、ダッシュボードを使用して、ポータル内でユーザーに許可する操作を定義します。商品カタログと価格カタログに基づいて、*サンドボックス* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes)と本番環境の設定を選択します。 > Stripe Connect でカスタマーポータルを使用している場合は、連結アカウントではなく、プラットフォームのカスタマーポータルを設定してください。 顧客のセットごとに異なる複数のポータル設定を作成する場合、または *Connect* (Connect is Stripe's solution for multi-party businesses, such as marketplace or software platforms, to route payments between sellers, customers, and other recipients) プラットフォームとして連結アカウントの設定を管理する場合は、[API](https://docs.stripe.com/api/customer_portal/configurations/object.md) を使用して設定できます。 ```curl curl https://api.stripe.com/v1/billing_portal/configurations \ -u "<>:" \ -d "features[invoice_history][enabled]=true" ``` ### 商品カタログを設定する 顧客が定期支払いのアップグレード、ダウングレード、数量の変更を実行できるようにする場合は、商品カタログの設定も必要です。これには、顧客がアップグレードまたはダウングレードできる対象の商品と価格、および顧客が数量を更新できる定期支払いが掲載されます。商品と価格の作成について、詳細は[商品を作成する](https://docs.stripe.com/products-prices/manage-prices.md#create-product)方法をご覧ください。カスタマーポータルを請求処理にのみ使用している場合は、商品カタログを設定する必要はありません。 ポータルには、商品カタログの以下の属性が表示されます。 - **商品名と説明**: これらの属性は、ダッシュボードと API で編集できます。 - **商品ごとの数量制限**: これらの属性は、ダッシュボードで編集できます。 - **金額、通貨、請求期間**: これらの属性は固定されており、ダッシュボードと API で作成するときにのみ設定できます。 ### 納税者番号の収集を有効にする [Stripe Tax](https://docs.stripe.com/tax.md) を使用してサブスクリプションや請求書の税金を自動徴収する場合、カスタマーポータルで、顧客に納税番号の設定と更新を行ってもらえます。Stripe Billing はその顧客の*請求書* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice)に納税者番号を追加します。顧客による納税者番号の設定を許可するには、[カスタマーポータルの設定](https://dashboard.stripe.com/settings/billing/portal)に移動して **納税者番号** をオンに切り替えます。詳細については、顧客の納税者番号が[サブスクリプション](https://docs.stripe.com/billing/customer/tax-ids.md)と[請求書](https://docs.stripe.com/invoicing/taxes/account-tax-ids.md)でどのように機能するかをご確認ください。 [Stripe Tax の設定](https://docs.stripe.com/tax/set-up.md)、[継続支払いの税金の徴収](https://docs.stripe.com/billing/taxes/collect-taxes.md)、[カスタムの決済フローでの税金の徴収](https://docs.stripe.com/tax/custom.md#existing-customer)、および[ラインアイテムと請求書の税率の設定](https://docs.stripe.com/tax/invoicing.md)の方法についてご紹介します。 ### プレビューしてテストする 設定を行う際に、**プレビュー** をクリックしてポータルをプレビューします。これにより、ポータルの読み取り専用バージョンが表示され、顧客がサブスクリプションや請求の詳細をどのように管理しているかを確認できます。 設定の保存後に、サンドボックスの顧客を使用してポータルを起動し、テストできます。ダッシュボードで顧客に移動し、**アクション**をクリックしてから、**カスタマーポータルを開く**を選択します。 ポータルを読み取り専用バージョンとしてプレビューできるのは、ダッシュボードをサンドボックス内で使用する場合のみです。ポータルをプレビューしてテストできない場合は、設定をチェックして、ポータル設定がサンドボックスに保存されていることを確認してください。プレビューとテストを有効にするには、ダッシュボードでの編集権限も変更する必要があります。 ## サイトにリダイレクトを実装する [クライアント側] [サーバー側] ポータルセッションはカスタマーポータルへのエントリーポイントです。ここには、ポータルへの固有で一時的なリンクが表示されます。顧客が請求または請求書の自己管理を希望する場合には、新しいポータルセッションを作成して、顧客をそのセッションの `url` にリダイレクトします。 顧客がクリックしてポータルに移動するためのボタンをサイトに追加します。POST リクエストを使用してポータルセッションを作成します。 ```html
``` 次に、ポータルセッションを作成して顧客をリダイレクトするエンドポイントを追加します。セッションを作成する前に、サイトで顧客を認証してください。[セッションを作成](https://docs.stripe.com/api/customer_portal/sessions/create.md)するには、顧客の ID と `return_url` が必要です。これは、ダッシュボードの設定でデフォルトの戻り先 URL が設定されていない場合に要求されます。 ポータルセッションを作成すると、Stripe は `portal session object` を返します。これには、顧客がカスタマーポータルにアクセスするために使用する、セッションの [短期間有効な URL](https://docs.stripe.com/api/customer_portal/sessions/object.md?lang=curl#portal_session_object-url) が含まれています。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ --data-urlencode "return_url=https://example.com/account" ``` ## Webhook をリッスンする [サーバー側] サブスクリプションのアップグレード、ダウングレード、キャンセルが実行された場合、顧客が実際に登録している商品またはサービスのみを受け取るようにする必要があります。Stripe は *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して、お客様の実装にこれらの変更を通知します。`Event` オブジェクトでサブスクリプションまたは顧客の ID を参照して、イベントが適用される顧客を特定します。 顧客がカスタマーポータルで請求先情報を更新したら、顧客レコードを更新することが重要です。更新を検知するには `customer.updated` Webhook を使用してください。 Stripe は、請求書の支払いが行われると、*Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して実装への通知も行います。`Event` オブジェクトで請求書または顧客の ID を参照して、イベントに該当する顧客を判断します。 これまでに Stripe で Webhook エンドポイントを設定していなかった場合、Stripe の [Webhook ドキュメント](https://docs.stripe.com/webhooks.md)を参照して設定を行うと、以下のイベントをリッスンできるようになります。 | イベント | 説明 | | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) | これをリッスンして、サブスクリプションのアップグレードとダウングレードをモニタリングします。アップグレードの場合は、Subscription オブジェクトの `subscription.items.data[0].price` 属性を確認して、顧客がサブスクリプションを登録する価格を確認します。次に、新しい商品へのアクセス権を付与します。ダウングレードの場合は、同じ属性を確認して、必要に応じてアクセスを調整または取り消します。 顧客がポータルを使用して[トライアル](https://docs.stripe.com/billing/subscriptions/trials.md)のあるサブスクリプションをアップグレードまたはダウングレードする場合、新しい料金に切り替わると直ちにサブスクリプションのトライアルが終了します。 | | [customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) | これをリッスンして、サブスクリプションの数量の更新を監視します。このイベントを受け取ったら、`subscription.items.data[0].quantity` 属性を確認して、顧客がサブスクリプションを登録する数量を確認します。次に、新しい数量へのアクセス権を付与します。 | | [customer.subscription.deleted](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.deleted) | これをリッスンすると、サブスクリプションのキャンセルを監視できます。このイベントを受信したら、顧客の商品へのアクセスを取り消します。請求期間の終了時にサブスクリプションをキャンセルするようポータルで設定している場合は、[customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) イベントをリッスンすると、キャンセルが発生する前に通知を受け取れます。柔軟な[請求モード](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-billing_mode)のサブスクリプションでは、`cancel_at` が `null` でなければ、サブスクリプションは請求期間の終了時にキャンセルされます。従来の請求モードのサブスクリプションでは、`cancel_at_period_end` が `true` であることを確認します。 顧客が気が変わった場合は、請求期間の終了前にサブスクリプションを再有効化できます。この場合、[customer.subscription.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.subscription.updated) イベントが送信されます。柔軟な請求モードのサブスクリプションでは、`cancel_at` が `null` であることを確認して、再有効化を確定します。従来の請求モードでは、`cancel_at_period_end` が `false` であることを確認します。 | | [payment_method.attached](https://docs.stripe.com/api/events/types.md#event_types-payment_method.attached) | 顧客が支払い方法を追加したときに発生します。 | | [payment_method.detached](https://docs.stripe.com/api/events/types.md#event_types-payment_method.detached) | 顧客が支払い方法を削除したときに発生します。 | | [customer.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.updated) | `invoice_settings.default_payment_method` 属性を確認して、顧客が新しいデフォルトとして選択した支払い方法を判断します。顧客レベルのデフォルトの支払い方法を上書きするサブスクリプションがある場合には、顧客はこの上書きを削除できます。このイベントを受け取ったときのサブスクリプションの `default_payment_method` 属性を確認し、上書きが削除されたかどうかを確認します。この Webhook を使用してデータベース内の関連する情報をすべて更新します。更新はすべて請求先情報の変更としてのみ扱う必要があります。顧客の請求先メールアドレスを、ログイン認証情報として使用しないでください。 | | [customer.tax_id.created](https://docs.stripe.com/api/events/types.md#event_types-customer.tax_id.created) | 顧客が納税者番号を管理するときに発生します。Stripe は一部のタイプの納税者番号を検証できます。詳細については、[納税者番号のガイド](https://docs.stripe.com/billing/customer/tax-ids.md)をご覧ください。 | | [customer.tax_id.deleted](https://docs.stripe.com/api/events/types.md#event_types-customer.tax_id.deleted) | 顧客が納税者番号を管理するときに発生します。Stripe は一部のタイプの納税者番号を検証できます。詳細については、[納税者番号のガイド](https://docs.stripe.com/billing/customer/tax-ids.md)をご覧ください。 | | [customer.tax_id.updated](https://docs.stripe.com/api/events/types.md#event_types-customer.tax_id.updated) | これをリッスンして、顧客の納税者番号に関する検証の更新を取得します。詳細については、[納税者番号のガイド](https://docs.stripe.com/billing/customer/tax-ids.md)をご覧ください。 | | [billing_portal.configuration.created](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.configuration.created) | 設定が作成されたときに発生します。 | | [billing_portal.configuration.updated](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.configuration.updated) | 設定が更新されたときに発生します。 | | [billing_portal.session.created](https://docs.stripe.com/api/events/types.md#event_types-billing_portal.session.created) | ポータルセッションが作成されたときに発生します。 | ## 本番環境へ移行 ポータルは、本番環境で有効にする前に必ずテストしてください。本番環境に移行する準備ができたら以下のことを行います。 ポータルセッションを作成すると、Stripe は `portal session` オブジェクトを返します。このオブジェクトには、カスタマーポータルにアクセスするために顧客が使用する必要のあるセッションの [短期間有効な URL](https://docs.stripe.com/api/customer_portal/sessions/object.md?lang=curl#portal_session_object-url) が含まれています。また、[login_page](https://docs.stripe.com/api/customer_portal/configurations/object.md#portal_configuration_object-login_page) パラメーターを使用して、ポータルの各構成に対して共有可能なリンクを 1 つ作成することもできます。 - ダッシュボードの**テストデータを表示**をオフにします。 - 本番環境でポータルを[設定](https://dashboard.stripe.com/settings/billing/portal)します。 - 本番環境で [Webhook](https://dashboard.stripe.com/webhooks) を追加します。 Stripe には、本番環境とサンドボックスの 2 種類のポータル設定があります。統合の検証をサポートするため、一方のモードに変更を加えても、もう一方のモードには影響しません。 ## Optional: 特定のページへのディープリンク 顧客のアクションを簡素化したり、アプリと Stripe の間のワークフローをさらにカスタマイズすることができます。カスタマーポータルのディープリンクを使用すると、実行するアクションが指定されたページに直接リンクして、顧客がアクションを完了した後のリダイレクト動作をカスタマイズすることができます。詳しくは、[カスタマーポータルのディープリンク](https://docs.stripe.com/customer-management/portal-deep-links.md)をご覧ください。 ## Optional: ポータルセッションをカスタマイズする [サーバー側] 顧客のグループごとに有効にする商品、価格、機能のセットを変えることができます。ポータルセッションに固有の設定を使用するには、ポータルを起動するときに上書きとして設定します。それ以外の場合は、ポータルではデフォルト設定が使用されます。 ダッシュボードはデフォルト設定の作成と更新をサポートしています。その他の設定は [API](https://docs.stripe.com/api/customer_portal/configurations/object.md) を使用して他の構成のみを管理できます。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d configuration={{CONFIGURATION_ID}} ``` Connect プラットフォームの場合は、ポータルを起動するときに `on_behalf_of` を指定できます。これにより、ポータルセッションのブランディング、ロゴ、会社名に `on_behalf_of` アカウントが反映されます。さらに、ポータルには、指定された `on_behalf_of` アカウントのサブスクリプションと請求書のみが表示されます。`on_behalf_of` の詳細については、[on_behalf_of のドキュメント](https://docs.stripe.com/connect/separate-charges-and-transfers.md#settlement-merchant)をご覧ください。 ```curl curl https://api.stripe.com/v1/billing_portal/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d configuration={{CONFIGURATION_ID}} \ -d on_behalf_of={{CONNECTED_ACCOUNT_ID}} ``` ## Optional: ブランディングをカスタマイズする ポータルをカスタマイズするには、以下の手順に従います。 1. [ブランディング設定](https://dashboard.stripe.com/settings/branding)ページに移動し、アイコンまたはロゴをアップロードし、カラーをカスタマイズします。 1. [公開アカウント設定](https://dashboard.stripe.com/settings/public)ページに移動し、公開ビジネス名と情報を確認します。