サブスクリプションの実装を構築する

サブスクリプションを作成して、継続支払いを受け付けるように管理します。

ウェブ

iOS

Android

React Native

ローコード

Appearance API を使用してカスタマイズします。

このガイドで、固定料金のサブスクリプションを販売する方法をご覧いただけます。Payment Element と Checkout Sessions API を使用して、アプリケーションに埋め込むカスタムの決済フォームを作成できます。

カスタムの決済フォームを作成しない場合は、ホストされた Checkout に導入することもできます。一連の導入手順を説明している実践的なガイドについては、Billing のクイックスタートを参照してください。

導入をコーディングする準備ができていなくても、基本的なサブスクリプションを Dashboard から手動で設定できます。また、Payment Links を使用して、コードを記述することなくサブスクリプションを設定することもできます。何を決定する必要があり、どのようなリソースが必要なのかを把握するために、導入の設計方法を確認してください。

作成する内容

このガイドでは以下の方法について説明します。

商品カタログを構築して、ビジネスをモデル化します。
顧客を作成する登録プロセスを構築します。
サブスクリプションを作成して、決済情報を収集します。
決済とサブスクリプションのステータスをテストして、モニタリングします。
顧客がプランを変更またはサブスクリプションをキャンセルできるようにします。

API オブジェクトの定義

リソース	定義
Customer (顧客)	サブスクリプションを購入する顧客を表します。サブスクリプションに関連付けられた Customer オブジェクトを使用して、継続支払いを作成して追跡し、顧客が登録する商品を管理します。
Entitlement (エンタイトルメント)	顧客が登録したサービス商品に含まれる機能への顧客のアクセスを表します。顧客の商品の継続購入のサブスクリプションを作成すると、その商品に関連付けられた機能ごとに、有効な権利が自動的に作成されます。顧客がサービスにアクセスするときに、その有効な資格を使用して、サブスクリプションに含まれる機能を有効にします。
Feature (機能)	顧客がサービス商品に登録すると利用できる機能や機能を表します。ProductFeatures を作成することで、商品に機能を含めることができます。
Invoice (請求書)	顧客が支払うべき金額の明細書であり、下書きから支払い済み、またはその他の方法で確定された支払いステータスを追跡します。サブスクリプションでは請求書が自動的に生成されます。
PaymentIntent	動的な支払いフローを構築する方法です。Payment Intent は、顧客の決済フローのライフサイクルを追跡し、規制で必須とされる同意書、Radar のカスタムの不正利用ルール、またはリダイレクトベースの支払い方法によって要求されたときに、追加の認証ステップを開始します。Payment Intent は、請求書によって自動的に作成されます。
PaymentMethod	顧客が商品の支払いに使用する決済手段。たとえば、クレジットカードを Customer オブジェクトに保存して、その顧客の継続支払いに使用できます。通常、Payment Intents API または Setup Intents API とともに使用されます。
Price (価格)	商品の単価、通貨、請求期間を定義します。
Product (商品)	お客様のビジネスが販売する商品またはサービス。サービス商品には 1 つ以上の機能を含めることができます。
ProductFeature	1 つの商品に 1 つの機能が含まれることを表します。各商品は、含まれる各機能の ProductFeature に関連付けられ、各機能は、それを含む各商品の ProductFeature に関連付けられます。
Subscription (サブスクリプション)	顧客の商品の継続的な購入を表します。サブスクリプションを使用して、支払いを回収し、商品の繰り返し提供や継続的なアクセスを提供します。

製品、機能、利用権がどのように連携するかの例をご紹介します。例えば、基本機能を提供する標準プランと、拡張機能を追加した上位プランの 2 つのプランを持つ定期サービスを設定するとします。

basic_features と extended_features の 2 つの機能を作成します。
standard_product と advanced_product の 2 つの商品を作成します。
標準商品の場合、basic_features を standard_product に関連付ける ProductFeature を 1 つ作成します。
高度な商品の場合、2 つの ProductFeatures を作成します。1 つは basic_features を advanced_product に関連付け、もう 1 つは extended_features を advanced_product に関連付けます。

顧客の first_customer は、標準商品に登録します。サブスクリプションを作成すると、Stripe は、first_customer を basic_features に関連付けるエンタイトルメントを自動的に作成します。

別の顧客no　second_customer は高度な商品に登録します。サブスクリプションを作成すると、Stripe は自動的に 2 つのエンタイトルメントを作成します。1 つは second_customer を basic_features に関連付け、もう 1 つは second_customer を extended_features に関連付けます。

有効なエンタイトルメントを取得するか、有効なエンタイトルメントのサマリーイベントをリッスンすることで、顧客に提供する機能を決定できます。顧客のサブスクリプション、商品、機能を取得する必要はありません。

Stripe をセットアップする

任意の Stripe クライアントをインストールします。

次に Stripe CLI をインストールします。CLI は Webhook のテストを提供します。これを実行すると Stripe への API コールを実行できます。このガイドの後続セクションでは、CLI を使った料金体系モデルの設定方法を紹介します。

Command Line
言語を選択homebrew
ソースからインストールする
 No results
# Install Homebrew to run this command: https://brew.sh/
brew install stripe/stripe-cli/stripe

# Connect the CLI to your dashboard
stripe login

その他のインストールオプションについては、Stripe CLI を使ってみるをご覧ください。

価格モデルを作成する
Stripe CLI またはダッシュボード

ダッシュボードまたは Stripe CLI で商品とその価格を作成します。

この例では、「基本」と「プレミアム」という 2 つのサービスレベルオプションがある固定価格のサービスを使用しています。サービスレベルオプションごとに、1 つの商品と 1 つの継続価格を作成する必要があります (初期費用のような 1 回限りの支払いを追加する場合は、1 回限りの価格で 3 つ目の商品を作成します。わかりやすくするために、この例には 1 回限りの支払いを含めていません)。

この例では、各商品が 1 カ月間隔で請求されます。基本商品の価格は 5 USD で、プレミアム商品の価格は 15 USD です。

商品を追加ページに移動し、2 つの商品を作成します。商品ごとに 1 つの価格を追加し、それぞれに毎月の継続請求期間を設定します。

プレミアム商品: 追加機能を備えたプレミアムサービス
- 価格：定額 | 15 USD
基本商品: 最低限の機能を備えた基本サービス
- 価格：定額 | 5 USD

価格を作成したら、価格 ID を記録しておき、他のステップで使用できるようにします。価格 ID は、price_G0FvDp6vZvdwRZ のように表示されます。

準備が完了したら、ページ右上の本番環境にコピーボタンを使用して、サンドボックスから本番環境に商品を複製します。

顧客の作成
クライアントおよびサーバー

Stripe では各サブスクリプションに対して顧客が必要です。アプリケーションのフロントエンドで、ユーザーから必要な情報を収集し、それをバックエンドに渡します。

住所の詳細を収集する必要がある場合は、Address Element を使用することで顧客の配送先住所または請求先住所を収集できます。Address Element の詳細については、Address Element ページをご覧ください。

register.html
<form id="signup-form">
  <label>
    Email
    <input id="email" type="email" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>

register.js
const emailInput = document.querySelector('#email');

fetch('/create-customer', {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: emailInput.value,
  }),
}).then(r => r.json());

サーバー上で、Stripe Customer オブジェクトを作成します。

注

Checkout セッションで使用するために、顧客 ID を必ず保存してください

Checkout Session を作成
サーバー

アプリケーションのバックエンドで、フロントエンドが呼び出すセッションを作成するエンドポイントを定義します。顧客が登録するサブスクリプションの価格 ID が必要です。フロントエンドはこの値を渡します。

ステップ 2 で 1 回限りの価格を作成した場合は、その価格 ID も渡します。Checkout Session を作成したら、レスポンスで client secret をクライアントに必ず渡してください。

注

lookup_keys を使用して、価格 ID ではなく価格を取得できます。例については、サンプルアプリケーションを参照してください。

ダッシュボードで、顧客から受け付ける支払い方法を有効にします。決済は複数の支払い方法に対応しています。

Checkout を初期化する
クライアント

Client Secret を解決する clientSecret Promise を作成するか、機密事項として直接設定します。initCheckout を呼び出し、clientSecret を渡します。initCheckout は、Checkout インスタンスに解決するプロミスを返します。

checkout オブジェクトは、チェックアウトページの基盤として機能し、Checkout Session のデータや Session を更新するためのメソッドを含みます。

actions.getSession() によって返されるオブジェクトには、価格情報が含まれます。セッションの 合計 と lineItems を UI で読み込んで表示することをお勧めします。

これにより、最小限のコード変更で新機能を有効にできます。たとえば、手動通貨価格を追加しても、合計 を表示する場合、 UI を変更する必要はありません。

checkout.js
const clientSecret = fetch('/create-checkout-session', {method: 'POST'})
  .then((response) => response.json())
  .then((json) => json.checkoutSessionClientSecret);
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();
if (loadActionsResult.type === 'success') {
  const session = loadActionsResult.actions.getSession();
  const checkoutContainer = document.getElementById('checkout-container');
  checkoutContainer.append(JSON.stringify(session.lineItems, null, 2));
  checkoutContainer.append(document.createElement('br'));
  checkoutContainer.append(`Total: ${session.total.total.amount}`);
}

index.html
<div id="checkout-container"></div>

決済情報を収集する
クライアント

Payment Element を使用して、クライアントで支払い情報を収集します。Payment Element は、さまざまな決済手段で支払い情報の収集を簡略化する事前構築済みの UI コンポーネントです。

まず、コンテナーの DOM 要素を作成して、Payment Element をマウントします。次に、checkout.createPaymentElement を使用して Payment Element のインスタンスを作成し、element.mount を呼び出してマウントし、CSS セレクターまたはコンテナーの DOM 要素を指定します。

index.html
<div id="payment-element"></div>

checkout.js
const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');

対応しているオプションについては、Stripe.js のドキュメントをご覧ください。

フロントエンドで Checkout を初期化するときに elementsOptions.appearance を渡すことで、すべての Elements のデザインをカスタマイズできるようになります。

支払いを送信
クライアント側

チェックアウトインスタンスから confirm を呼び出す支払うボタンをレンダリングして、決済を送信します。

index.html
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>

checkout.js
const checkout = stripe.initCheckout({clientSecret});
const loadActionsResult = await checkout.loadActions();

if (loadActionsResult.type === 'success') {
  const {actions} = loadActionsResult;
  const button = document.getElementById('pay-button');
  const errors = document.getElementById('confirm-errors');
  button.addEventListener('click', () => {
    // Clear any validation errors
    errors.textContent = '';

    actions.confirm().then((result) => {
      if (result.type === 'error') {
        errors.textContent = result.error.message;
      }
    });
  });
}

Webhook をリッスンする
サーバー

実装を完了するには、Stripe から送信される webhooks を処理する必要があります。これらのイベントは、サブスクリプションの新しい請求書が生成されるなど、Stripe でステータスが変更されるたびに発生します。お客様のアプリケーション側では、webhook イベントを含む POST リクエストを受け取るための HTTP ハンドラーを設定して、イベントの署名を検証してください。

開発中は、Stripe CLI を使用して Webhook をモニタリングし、アプリケーションに転送します。開発アプリの実行中に、新しい端末で以下を実行します。

Command Line
stripe listen --forward-to localhost:4242/webhook

本番環境では、ダッシュボードで Webhook エンドポイント URL を設定するか、Webhook Endpoints API を使用します。

いくつかのイベントをリッスンして、このガイドの残りのステップを完了する必要があります。サブスクリプション固有の Webhook の詳細については、サブスクリプションのイベントを参照してください。

サービスへのアクセスを提供する
クライアントおよびサーバー

サブスクリプションが有効になりました。次は、ユーザーがサービスにアクセスできるようにします。これを行うには、customer.subscription.created、customer.subscription.updated、customer.subscription.deleted の各イベントをリッスンします。これらのイベントは、サブスクリプションオブジェクトを渡します。このオブジェクトには、サブスクリプションが有効か、期日経過か、キャンセルされたかを示すステータス フィールドが含まれます。ステータスの一覧については、サブスクリプションのライフサイクルを参照してください。

Webhook ハンドラーで、以下を実行します。

サブスクリプションのステータスを確認します。active の場合、ユーザーは商品の決済を実行しています。
顧客が登録している商品を確認し、サービスへのアクセス権を付与します。価格ではなく商品を確認することにより、料金体系や請求期間の変更が必要になった場合に、柔軟に対応できます。
product.id、subscription.id および subscription.status を、すでに保存されている customer.id とともにデータベースに保存します。アプリケーションでユーザーに対して有効にする機能を決定する際に、このレコードを確認します。

サブスクリプションのステータスは、アプリケーションから直接 Stripe に呼び出しを行わなくても、そのライフサイクルのどの時点でも変更される可能性があります。たとえばクレジットカードの有効期限切れで更新ができなかった場合、サブスクリプションは past due のステータスになります。または、お客様が customer portal を実装している場合、顧客はお客様のアプリケーションに直接アクセスせずにサブスクリプションをキャンセルする可能性があります。ハンドラーを正しく実装することで、お客様のアプリケーションのステータスを Stripe と同期した状態に維持することができます。

サブスクリプションをキャンセルする
クライアントおよびサーバー

顧客にサブスクリプションのキャンセルを許可するのは一般的です。この例では、アカウントの設定ページにキャンセルオプションを追加します。

サブスクリプションのキャンセル機能が設定されたアカウント設定

script.js
function cancelSubscription(subscriptionId) {
  return fetch('/cancel-subscription', {
    method: 'post',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(cancelSubscriptionResponse => {
      // Display to the user that the subscription has been canceled.
    });
}

バックエンド側で、フロントエンドが呼び出すためのエンドポイントを定義してください。

アプリケーションが customer.subscription.deleted イベントを受信します。

サブスクリプションがキャンセルされたら、以前保存していた Stripe のサブスクリプション ID をデータベースから削除し、サービスへのアクセスを制限します。

サブスクリプションをキャンセルすると、再度アクティブにすることはできません。代わりに、顧客から請求先情報の更新を収集し、顧客のデフォルトの決済手段を更新して、既存の顧客レコードから新しいサブスクリプションを作成します。

導入をテストする

支払い方法をテストする

次の表を使用して、さまざまな支払い方法とシナリオをテストします。

決済手段	シナリオ	テスト方法
BECS ダイレクトデビット	顧客が BECS ダイレクトデビットによる支払いに成功します。	アカウント番号`900123456`と BSB`000000`を使用して、フォームに入力します。確定された PaymentIntent のステータスは、まず`processing`に移行し、3 分後に`succeeded`ステータスに移行します。
BECS ダイレクトデビット	顧客の支払いが `account_closed` エラーコードで失敗します。	アカウント番号 `111111113`と BSB `000000`を使用して、フォームに入力します。
クレジットカード	カード支払いは成功し、認証は必要とされません。	クレジットカード番号 `4242 4242 4242 4242` と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。
クレジットカード	カード決済で認証が要求されます。	クレジットカード番号 `4000 0025 0000 3155` と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。
クレジットカード	カードが `insufficient_funds` などの拒否コードで支払い拒否されます。	クレジットカード番号 `4000 0000 0000 9995` と、任意の有効期限、セキュリティコード、郵便番号を使用してクレジットカードフォームに入力します。
SEPA ダイレクトデビット	顧客が SEPA ダイレクトデビットによる支払いに成功します。	口座番号 `AT321904300235473204` を使用して、フォームに入力します。確定された PaymentIntent のステータスはまず、processing に移行し、3 分後に succeeded ステータスに移行します。
SEPA ダイレクトデビット	顧客の PaymentIntent ステータスが `processing` から `requires_payment_method` に移行します。	口座番号 `AT861904300235473202` を使用して、フォームに入力します。

イベントを監視する

Webhook を設定して、アップグレードやキャンセルなどのサブスクリプション変更イベントをリッスンします。サブスクリプション Webhook の詳細については、ダッシュボードまたは Stripe CLI で表示できます。

詳しくは、請求導入のテストを参照してください。

オプション顧客がプランを変更できるようにする
クライアントおよびサーバー

顧客にサブスクリプションの変更を許可するには、変更後のオプションの価格 ID を収集します。次にフロントエンドからバックエンドのエンドポイントにこの新しい価格 ID を送信します。この例ではサブスクリプション ID も渡していますが、ログインしているユーザーのデータベースから取得できます。

script.js
function updateSubscription(priceId, subscriptionId) {
  return fetch('/update-subscription', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      subscriptionId: subscriptionId,
      newPriceId: priceId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then(response => {
      return response;
    });
}

フロントエンドから呼び出すエンドポイントをバックエンドで定義し、サブスクリプション ID と新しい価格 ID を渡します。これで、サブスクリプションは、月額 5 USD の基本オプションではなく、月額 15 USD のプレミアムオプションになりました。

アプリケーションが customer.subscription.updated イベントを受信します。

オプション価格変更をプレビューする
クライアントおよびサーバー

顧客がサブスクリプションを変更すると、多くの場合、顧客が支払う金額の調整 (比例配分) が発生します。プレビュー請求書エンドポイントを使用することで、調整済みの金額を顧客に表示できます。

フロントエンドから、プレビュー請求書作成の詳細情報をバックエンドのエンドポイントに渡してください。

script.js
function createPreviewInvoice(
  customerId,
  subscriptionId,
  newPriceId,
  trialEndDate
) {
  return fetch('/create-preview-invoice', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      customerId: customerId,
      subscriptionId: subscriptionId,
      newPriceId: newPriceId,
    }),
  })
    .then(response => {
      return response.json();
    })
    .then((invoice) => {
      return invoice;
    });
}

バックエンド側で、フロントエンドが呼び出すためのエンドポイントを定義してください。

オプション顧客の決済手段を表示する
クライアントおよびサーバー

顧客のカードのブランドとカード番号の下 4 桁を表示すると、顧客はチャージに使用するカードを確認したり、決済手段の更新が必要かどうかを判断したりできます。

フロントエンドから、決済手段の詳細を取得するバックエンドのエンドポイントに、決済手段 ID を送信します。

script.js
function retrieveCustomerPaymentMethod(paymentMethodId) {
  return fetch('/retrieve-customer-payment-method', {
    method: 'post',
    headers: {
      'Content-type': 'application/json',
    },
    body: JSON.stringify({
      paymentMethodId: paymentMethodId,
    }),
  })
    .then((response) => {
      return response.json();
    })
    .then((response) => {
      return response;
    });
}

バックエンド側で、フロントエンドが呼び出すためのエンドポイントを定義してください。

レスポンス例を以下に示します。

{
  "id": "pm_1GcbHY2eZvKYlo2CoqlVxo42",
  "object": "payment_method",
  "billing_details": {
    "address": {
      "city": null,
      "country": null,
      "line1": null,
      "line2": null,
      "postal_code": null,

注

paymentMethod.id および last4 は、データベースに保存することをお勧めします。たとえば、paymentMethod.id を stripeCustomerPaymentMethodId として users コレクションまたはテーブルに保存します。必要に応じて、exp_month、exp_year、fingerprint、billing_details を保存することもできます。これは Stripe に対して実行するコール数を制限するためのものであり、パフォーマンスの効率を向上させ、レート制限の防止に役立ちます。

顧客に Stripe を開示する

Stripe は顧客の Elements とのやり取りに関する情報を収集して、サービスを提供し、不正利用を防止し、サービスを向上します。これには、Cookie と IP アドレスを使用して、1 つの決済フローセッションで顧客に表示する Elements を特定することが含まれます。Stripe がこのような方法でデータを使用するために必要なすべての権利と同意について開示し、これらを取得することはお客様の責任です。詳細については、プライバシーセンターをご覧ください。

注

サブスクリプションの実装を構築する

サブスクリプションを作成して、継続支払いを受け付けるように管理します。

作成する内容

API オブジェクトの定義

Stripe をセットアップする

価格モデルを作成するStripe CLI またはダッシュボード

顧客の作成クライアントおよびサーバー

注

Checkout Session を作成サーバー

注

Checkout を初期化するクライアント

決済情報を収集するクライアント

支払いを送信クライアント側

Webhook をリッスンするサーバー

サービスへのアクセスを提供するクライアントおよびサーバー

サブスクリプションをキャンセルするクライアントおよびサーバー

導入をテストする

支払い方法をテストする

イベントを監視する

オプション顧客がプランを変更できるようにするクライアントおよびサーバー

オプション価格変更をプレビューするクライアントおよびサーバー

オプション顧客の決済手段を表示するクライアントおよびサーバー

注

顧客に Stripe を開示する

価格モデルを作成する
Stripe CLI またはダッシュボード

顧客の作成
クライアントおよびサーバー

Checkout Session を作成
サーバー

Checkout を初期化する
クライアント

決済情報を収集する
クライアント

支払いを送信
クライアント側

Webhook をリッスンする
サーバー

サービスへのアクセスを提供する
クライアントおよびサーバー

サブスクリプションをキャンセルする
クライアントおよびサーバー

オプション顧客がプランを変更できるようにする
クライアントおよびサーバー

オプション価格変更をプレビューする
クライアントおよびサーバー

オプション顧客の決済手段を表示する
クライアントおよびサーバー