API でカスタマーポータルを実装する
Stripe API を使用してカスタマーポータルを実装する方法をご紹介します。
カスタマーポータルを使用すれば、構築を自身で行わなくても顧客がサブスクリプション、請求書、請求書を管理できるようにすることができます。ポータルの設定と導入を終えると、顧客は提携ブランドのダッシュボードにリダイレクトされます。そこで、顧客は設定された機能に基づいて各自のアカウントを管理できます。
アプリケーションをカスタマーポータルに組み込むには、以下の手順に従います。
- ポータルの機能とユーザーインターフェイス (UI) を設定します。これはダッシュボードで実行できます。
- リダイレクトを実装してアプリケーションにポータルを導入します。
- Webhook をリッスンして顧客のサブスクリプションと支払い方法の更新を受け取ります。
- 本番環境でのポータルの利用を開始します。
または、以下のサンプルプロジェクトのいずれかを複製します。
必要に応じて、ポータルセッションをカスタマイズし、顧客ごとに異なる機能を有効にできます。
ポータルを設定
First, you need to register for a Stripe account.
Before you integrate the customer portal, use the Dashboard to define what your users can do with the portal. Choose your settings for sandboxes and live mode, based on your product and price catalog.
よくある間違い
Stripe Connect でカスタマーポータルを使用している場合は、連結アカウントではなく、プラットフォームのカスタマーポータルを設定してください。
If you want to create multiple portal configurations for different sets of customers (or if you’re a Connect platform and want to manage configurations for your connected accounts), you can do so using the API:
商品カタログを設定する
If you allow customers to upgrade, downgrade, or change the quantities of their subscriptions, you must also set a product catalog. This includes the products and prices that your customers can upgrade or downgrade to, and the subscriptions they can update quantities on. See how to create a product for more details about creating products and prices. If you’re using the customer portal for invoicing only, you don’t need to set a product catalog.
ポータルには、商品カタログの以下の属性が表示されます。
- Product name and description—These attributes are editable in the Dashboard and API.
- Quantity restrictions per product—These attributes are editable in the Dashboard.
- Price amount, currency, and billing interval—These attributes are fixed, and you can only set them when you create them in the Dashboard and API.
納税者番号の収集を有効にする
If you use Stripe Tax to automatically collect taxes for subscriptions or invoices, you can let customers set and update their tax IDs in the customer portal. Stripe Billing adds the tax IDs to the customers’ invoices. To allow customers to set their tax IDs, go to the Customer portal settings and toggle on Tax ID. For more information, see how customer tax IDs work with subscriptions and invoices.
Stripe Tax の設定、継続支払いの税金の徴収、カスタムの決済フローでの税金の徴収、およびラインアイテムと請求書の税率の設定の方法についてご紹介します。
プレビューしてテストする
As you configure your settings, click Preview to preview the portal. This launches a read-only version of the portal that lets you see how your customers might manage their subscriptions and billing details.
設定を保存したらポータルを起動し、サンドボックスで顧客を使用してテストすることができます。ダッシュボードで顧客に移動し、アクションをクリックして、カスタマーポータルを開くを選択します。
You can only preview the portal as a read-only version when your Dashboard is in a sandbox. If you can’t preview and test the portal, check your settings to make sure that your configuration is saved in a sandbox. For previewing and testing to work, you also need to have edit permissions in the Dashboard.
サイトにリダイレクトを実装するクライアント側サーバー側
ポータルセッションはカスタマーポータルへのエントリーポイントです。ここには、ポータルへの固有で一時的なリンクが表示されます。顧客が請求または請求書の自己管理を希望する場合には、新しいポータルセッションを作成して、顧客をそのセッションの url にリダイレクトします。
顧客がクリックしてポータルに移動するためのボタンをサイトに追加します。POST リクエストを使用してポータルセッションを作成します。
<form method="POST" action="/create-customer-portal-session"> <button type="submit">Manage billing</button> </form>
次に、ポータルセッションを作成して顧客をリダイレクトするエンドポイントを追加します。セッションを作成する前に、サイトで顧客を認証してください。セッションを作成するには、顧客の ID と return_ が必要です。これは、ダッシュボードの設定でデフォルトの戻り先 URL が設定されていない場合に要求されます。
ポータルセッションを作成すると、Stripeは portal session object を返します。これには、顧客がカスタマーポータルにアクセスするために使用する、セッションのワンタイム URL が含まれます。
Webhook をリッスンするサーバー側
サブスクリプションのアップグレード、ダウングレード、キャンセルが実行された場合、顧客が実際に登録している商品またはサービスのみを受け取るようにする必要があります。Stripe は Webhook を使用して、お客様の実装にこれらの変更を通知します。Event オブジェクトでサブスクリプションまたは顧客の ID を参照して、イベントが適用される顧客を特定します。
Stripe は、請求書の支払いが行われると、Webhook を使用して実装への通知も行います。Event オブジェクトで請求書または顧客の ID を参照して、イベントに該当する顧客を判断します。
これまでに Stripe で Webhook エンドポイントを設定していなかった場合、Stripe の Webhook ドキュメントを参照して設定を行うと、以下のイベントをリッスンできるようになります。
| イベント | 説明 |
|---|---|
これをリッスンして、サブスクリプションのアップグレードとダウングレードをモニタリングします。アップグレードの場合は、Subscription オブジェクトの 顧客がポータルを使用してトライアルのあるサブスクリプションをアップグレードまたはダウングレードする場合、新しい料金に切り替わると直ちにサブスクリプションのトライアルが終了します。 | |
| customer.subscription.updated | これをリッスンして、サブスクリプションの数量の更新を監視します。このイベントを受け取ったら、subscription. 属性を確認して、顧客がサブスクリプションを登録する数量を確認します。次に、新しい数量へのアクセス権を付与します。 |
これをリッスンして、サブスクリプションのキャンセルを監視します。このイベントを受信したら、顧客の商品へのアクセスを取り消します。ポータルで請求期間終了時にサブスクリプションをキャンセルするよう設定している場合は、customer.subscription.updated イベントをリッスンして、キャンセルの実行前に通知を受け取るようにします。 顧客の考えが変わった場合、顧客は請求期間の終了前であればサブスクリプションを再び有効にできます。これが実行されると、customer.subscription.updated イベントが送信されます。 | |
| payment_method.attached | 顧客が支払い方法を追加したときに発生します。 |
| payment_method.detached | 顧客が支払い方法を削除したときに発生します。 |
| customer.updated | invoice_ 属性を確認して、顧客が新しいデフォルトとして選択した支払い方法を判断します。顧客レベルのデフォルトの支払い方法を上書きするサブスクリプションがある場合には、顧客はこの上書きを削除できます。このイベントを受け取ったときのサブスクリプションの default_ 属性を確認し、上書きが削除されたかどうかを確認します。この Webhook を使用してデータベース内の関連する情報をすべて更新します。更新はすべて請求先情報の変更としてのみ扱う必要があります。顧客の請求先メールアドレスを、ログイン認証情報として使用しないでください。 |
| customer.tax_id.created | 顧客が納税者番号を管理するときに発生します。Stripe は一部のタイプの納税者番号を検証できます。詳細については、納税者番号のガイドをご覧ください。 |
| customer.tax_id.deleted | 顧客が納税者番号を管理するときに発生します。Stripe は一部のタイプの納税者番号を検証できます。詳細については、納税者番号のガイドをご覧ください。 |
| customer.tax_id.updated | これをリッスンして、顧客の納税者番号に関する検証の更新を取得します。詳細については、納税者番号のガイドをご覧ください。 |
| billing_portal.configuration.created | 設定が作成されたときに発生します。 |
| billing_portal.configuration.updated | 設定が更新されたときに発生します。 |
| billing_portal.session.created | ポータルセッションが作成されたときに発生します。 |
本番環境へ移行
ポータルは、本番環境で有効にする前に必ずテストしてください。本番環境に移行する準備ができたら以下のことを行います。
ポータルセッションを作成すると、Stripe から portal session オブジェクトが返されます。これにはセッションの一時的な URL が含まれており、顧客がカスタマーポータルにアクセスする際はこの URL を使用する必要があります。また、login_page パラメーターを指定して、ポータルの設定ごとに共有可能なリンクを 1 件作成することもできます。
Stripe は、本番環境用に 1 つ、サンドボックスごとに 1 つずつ、異なるポータル設定セットを用意しています。システムを検証しやすくするために、一方の環境に変更を加えても、もう一方の環境の設定には影響しません。