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

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

カスタマーポータルを実装する前に、ダッシュボードで機能とブランディングを設定し、ユーザーがポータルで実行できる操作を定義します。機能は、商品と価格のカタログによって変わるため、サンドボックスと本番環境ではそれぞれ異なる設定が用意されています。

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

curl https://api.stripe.com/v1/billing_portal/configurations \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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 は、本番環境用に 1 つ、サンドボックスごとに 1 つずつ、異なるポータル設定セットを用意しています。システムを検証しやすくするために、一方の環境に変更を加えても、もう一方の環境の設定には影響しません。