API でカスタマーポータルを実装する

まず、Stripe アカウントが必要です。今すぐ登録してください。

カスタマーポータルを組み込む前に、ダッシュボードで機能とブランディングを設定し、ユーザーがポータルで実行できることを定義します。その機能は商品および価格カタログによって変わるため、本番環境とテスト環境では異なる設定があります。

さまざまな顧客に合わせて複数のポータル設定を作成する場合、または Connect プラットフォームで連結アカウントの設定を管理する場合、API を使用してこれを行うことができます。

curl https://api.stripe.com/v1/billing_portal/configurations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "features[invoice_history][enabled]"=true

商品カタログを設定する

顧客にサブスクリプションのアップグレード、ダウングレード、数量の変更を許可する場合は、商品カタログも設定する必要があります。これには、顧客がアップグレードまたはダウングレードできる商品と料金、および数量を更新できるサブスクリプションが含まれます。商品と料金の作成については、ガイドで詳細をご確認ください。カスタマーポータルを請求処理にのみ使用している場合は、商品カタログを設定する必要はありません。

ポータルには、商品カタログの以下の属性が表示されます。

• 商品名と説明: これらの属性は、ダッシュボードと 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 が必要です。これは、ダッシュボードの設定でデフォルトの戻り先 URL が設定されていない場合に要求されます。

ポータルセッションを作成すると、Stripeは portal session object を返します。これには、顧客がカスタマーポータルにアクセスするために使用する、セッションのワンタイム URL が含まれます。

curl https://api.stripe.com/v1/billing_portal/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d customer={{CUSTOMER_ID}} \
  --data-urlencode return_url="https://example.com/account"

サブスクリプションのアップグレード、ダウングレード、キャンセルが実行された場合、顧客が実際に登録している商品またはサービスのみを受け取るようにする必要があります。Stripe は Webhook を使用して、お客様の実装にこれらの変更を通知します。Event オブジェクトでサブスクリプションまたは顧客の ID を参照して、イベントが適用される顧客を特定します。

Stripe は、請求書の支払いが行われると、Webhook を使用して実装への通知も行います。Event オブジェクトで請求書または顧客の ID を参照して、イベントに該当する顧客を判断します。

これまでに Stripe で Webhook エンドポイントを設定していなかった場合、Stripe の Webhook ドキュメントを参照して設定を行うと、以下のイベントをリッスンできるようになります。

ポータルは、本番環境で有効にする前に必ずテストしてください。本番環境に移行する準備ができたら以下のことを行います。

ポータルセッションを作成すると、Stripe から portal session オブジェクトが返されます。これにはセッションの一時的な URL が含まれており、顧客がカスタマーポータルにアクセスする際はこの URL を使用する必要があります。また、login_page パラメーターを指定して、ポータルの設定ごとに共有可能なリンクを 1 件作成することもできます。

• ダッシュボードのテストデータを表示をオフにします。
• 本番環境でポータルを設定します。
• 本番環境で Webhook を追加します。

Stripe には、本番環境とテスト環境の、2 種類のポータル設定があります。実装の検証をサポートするため、一方の環境に変更を加えても、もう一方の環境には影響しません。