API でカスタマーポータルを実装する
Stripe API を使用してカスタマーポータルを実装する方法をご紹介します。
カスタマーポータルを使用すれば、構築を自身で行わなくても顧客がサブスクリプション、請求書、請求書を管理できるようにすることができます。ポータルの設定と導入を終えると、顧客は提携ブランドのダッシュボードにリダイレクトされます。そこで、顧客は設定された機能に基づいて各自のアカウントを管理できます。
アプリケーションをカスタマーポータルに組み込むには、以下の手順に従います。
- ポータルの機能とユーザーインターフェイス (UI) を設定します。これはダッシュボードで実行できます。
- リダイレクトを実装してアプリケーションにポータルを導入します。
- Webhook をリッスンして顧客のサブスクリプションと支払い方法の更新を受け取ります。
- 本番環境でのポータルの利用を開始します。
または、以下のサンプルプロジェクトのいずれかを複製します。
必要に応じて、ポータルセッションをカスタマイズし、顧客ごとに異なる機能を有効にできます。
ポータルを設定
まず、Stripe アカウントを登録する必要があります。
カスタマーポータルを実装する前に、ダッシュボードを使用して、ポータル内でユーザーに許可する操作を定義します。商品カタログと価格カタログに基づいて、サンドボックスと本番環境の設定を選択します。
よくある間違い
Stripe Connect でカスタマーポータルを使用している場合は、連結アカウントではなく、プラットフォームのカスタマーポータルを設定してください。
さまざまな顧客に合わせて複数のポータル設定を作成する場合 (または Connect プラットフォームで連結アカウントの設定を管理する場合) は、API を使用して行えます。
商品カタログを設定する
顧客が定期支払いのアップグレード、ダウングレード、数量の変更を実行できるようにする場合は、商品カタログの設定も必要です。これには、顧客がアップグレードまたはダウングレードできる対象の商品と価格、および顧客が数量を更新できる定期支払いが掲載されます。商品と価格の作成について、詳細は商品を作成する方法をご覧ください。カスタマーポータルを請求処理にのみ使用している場合は、商品カタログを設定する必要はありません。
ポータルには、商品カタログの以下の属性が表示されます。
- 商品名と説明: これらの属性は、ダッシュボードと API で編集できます。
- 商品ごとの数量制限: これらの属性は、ダッシュボードで編集できます。
- 金額、通貨、請求期間: これらの属性は固定されており、ダッシュボードと API で作成するときにのみ設定できます。
納税者番号の収集を有効にする
Stripe Tax を使用してサブスクリプションや請求書の税金を自動徴収する場合、カスタマーポータルで、顧客に納税番号の設定と更新を行ってもらえます。Stripe Billing はその顧客の請求書に納税者番号を追加します。顧客による納税者番号の設定を許可するには、カスタマーポータルの設定に移動して 納税者番号 をオンに切り替えます。詳細については、顧客の納税者番号がサブスクリプションと請求書でどのように機能するかをご確認ください。
Stripe Tax の設定、継続支払いの税金の徴収、カスタムの決済フローでの税金の徴収、およびラインアイテムと請求書の税率の設定の方法についてご紹介します。
プレビューしてテストする
設定を行う際に、プレビュー をクリックしてポータルをプレビューします。これにより、ポータルの読み取り専用バージョンが表示され、顧客がサブスクリプションや請求の詳細をどのように管理しているかを確認できます。
設定を保存したらポータルを起動し、サンドボックスで顧客を使用してテストすることができます。ダッシュボードで顧客に移動し、アクションをクリックして、カスタマーポータルを開くを選択します。
ポータルを読み取り専用バージョンとしてプレビューできるのは、ダッシュボードをサンドボックス内で使用する場合のみです。ポータルをプレビューしてテストできない場合は、設定をチェックして、ポータル設定がサンドボックスに保存されていることを確認してください。プレビューとテストを有効にするには、ダッシュボードでの編集権限も変更する必要があります。
サイトにリダイレクトを実装するクライアント側サーバー側
ポータルセッションはカスタマーポータルへのエントリーポイントです。ここには、ポータルへの固有で一時的なリンクが表示されます。顧客が請求または請求書の自己管理を希望する場合には、新しいポータルセッションを作成して、顧客をそのセッションの 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 つずつ、異なるポータル設定セットを用意しています。システムを検証しやすくするために、一方の環境に変更を加えても、もう一方の環境の設定には影響しません。