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

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

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

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

# 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 を使ってみるをご覧ください。

継続的な料金体系モデルは、お客様が販売する商品またはサービス、そのコスト、決済で受け付ける通貨、請求対象となるサービス提供期間 (サブスクリプションの場合) を表します。価格モデルを構築するには、お客様が販売する「商品」と、それをいくらで、どのくらいの頻度で請求するかを示す「価格」を用います。

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

各商品が月ごとに請求されます。基本商品の価格は 5 USD で、プレミアム商品の価格は 15 USD です。3 段階構成の例については、定額料金ガイドをご覧ください。

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

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

<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>

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 オブジェクトを作成します。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}} \
  -d name={{CUSTOMER_NAME}} \
  -d "shipping[address][city]"=Brothers \
  -d "shipping[address][country]"=US \
  -d "shipping[address][line1]"="27 Fredrick Ave" \
  -d "shipping[address][postal_code]"=97712 \
  -d "shipping[address][state]"=CA \
  -d "shipping[name]"={{CUSTOMER_NAME}} \
  -d "address[city]"=Brothers \
  -d "address[country]"=US \
  -d "address[line1]"="27 Fredrick Ave" \
  -d "address[postal_code]"=97712 \
  -d "address[state]"=CA

顧客がプランを選択してからサブスクリプションを作成できるようにします。このガイドの例では、顧客は Basic プランまたは Premium プランのいずれかを選択します。

フロントエンドで、選択した価格 ID と顧客レコードの ID をバックエンドに渡します。

fetch('/create-subscription', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    priceId: priceId,
    customerId: customerId,
  }),
})

バックエンドで、payment_behavior=default_incomplete を使用して incomplete ステータスのサブスクリプションを作成します。次に、サブスクリプションの最初の PaymentIntent からフロントエンドに client_secret を返して決済を完了します。これを行うには、サブスクリプションの最新請求書の confirmation_secret を展開します。

サブスクリプション動作の改善 を有効にするには、billing_mode[type] を flexible に設定します。Stripe API バージョン 2025-06-30.basil 以降を使用する必要があります。

決済が完了したときに決済手段をデフォルトとして保存する場合は、save_default_payment_method を on_subscription に設定します。デフォルトの決済手段を保存すると、その後のサブスクリプションの決済の成功率が高くなります。

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/create-subscription' do
  content_type 'application/json'
  data = JSON.parse(request.body.read)
  customer_id = cookies[:customer]
  price_id = data['priceId']

  # Create the subscription. Note we're expanding the Subscription's
  # latest invoice and that invoice's confirmation_secret
  # so we can pass it to the front end to confirm the payment
  subscription = Stripe::Subscription.create(
    customer: customer_id,
    items: [{
      price: price_id,
    }],
    payment_behavior: 'default_incomplete',
    payment_settings: {save_default_payment_method: 'on_subscription'},
    billing_mode: {type: 'flexible'},
    expand: ['latest_invoice.confirmation_secret']
  )

  { subscriptionId: subscription.id, clientSecret: subscription.latest_invoice.confirmation_secret.client_secret }.to_json
end

サブスクリプションは inactive になり、決済を待っています。以下のレスポンスの例では、保存が必要な最小限のフィールドが強調表示されていますが、アプリケーションで頻繁にアクセスされるフィールドは保存できます。

{
  "id": "sub_JgRjFjhKbtD2qz",
  "object": "subscription",
  "application_fee_percent": null,
  "automatic_tax": {
    "disabled_reason": null,
    "enabled": false,
    "liability": "null"
  },
  "billing_cycle_anchor": 1623873347,

Stripe Elements を使用して決済の詳細を収集し、サブスクリプションを有効化します。Elements は、アプリケーションのデザインに合わせてカスタマイズできます。

Payment Element はサブスクリプションで Link、クレジットカード、SEPA ダイレクトデビット、BECS ダイレクトデビットをサポートします。有効な決済手段を表示し、顧客の選択に応じて決済詳細を安全に収集することができます。

Stripe Elements を設定する

Payment Element は Stripe.js の機能として自動的に使用できるようになります。決済ページに Stripe.js スクリプトを含めるには、HTML ファイルの head にスクリプトを追加します。常に js.stripe.com から Stripe.js を直接読み込むことにより、PCI 準拠が維持されます。スクリプトをバンドルに含めることや、そのコピーを自身でホストすることは避けてください。

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>
<body>
  <!-- content here -->
</body>

決済ページで以下の JavaScript を使用して、Stripe のインスタンスを作成します。

// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

Payment Element をページに追加する

決済ページには Payment Element を配置する場所が必要です。決済フォームで、一意の ID を持つ空の DOM ノード (コンテナー) を作成します。

<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Subscribe</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

このフォームが読み込まれた後、Payment Element のインスタンスを作成して、それをコンテナーの DOM ノードにマウントします。サブスクリプションの作成 で、フロントエンドに client_secret 値を渡しています。この値を、Elements のインスタンスを作成する際にオプションとして渡します。

const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in the payment form, passing the client secret obtained in step 5
const elements = stripe.elements(options);

const paymentElementOptions = {
  layout: "tabs",
};

// Create and mount the Payment Element
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Payment Element によって動的なフォームが表示され、顧客はここで決済手段を選択できます。このフォームでは、顧客が選択した決済手段で必要な決済の詳細のすべてが自動的に収集されます。

(オプション) Payment Element の設定

必要に応じて、以下を実行できます。

• Elements のインスタンスを作成する際に appearance オブジェクト を options に渡すことで、サイトのデザインに合わせて Payment Element をカスタマイズできます。
• Apple Pay インターフェイスを設定して、継続決済、自動リロード、後払いに対応する 加盟店トークン を返します。

決済を完了する

stripe.confirmPayment を使用して、Payment Element からの詳細を指定した決済を完了し、サブスクリプションを有効化します。これにより PaymentMethod が作成され、不完全なサブスクリプションの最初の PaymentIntent が確定され、請求が実行されます。チャージに 強力な顧客認証 (SCA) が必要とされる場合は、PaymentIntent の確定前に、Payment Element が認証プロセスを処理します。

決済の完了後に Stripe がユーザーをリダイレクトする場所を指定するには、return_url を指定します。まず、ユーザーを銀行の認証ページなどの中間サイトにリダイレクトしてから、return_url にリダイレクトすることができます。カード決済では、決済が正常に完了するとすぐに return_url にリダイレクトします。

const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: "https://example.com/order/123/complete",
    }
  });

  if (error) {
    // This point is reached only if there's an immediate error when
    // confirming the payment. Show an error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer redirects to your `return_url`. For some payment
    // methods, such as iDEAL, your customer redirects to an intermediate
    // site first to authorize the payment, and then redirects to the `return_url`.
  }
});

顧客が支払いを送信すると、Stripe は顧客を return_url にリダイレクトし、以下の URL クエリーパラメーターを含めます。返品ページでは、これらを使用して PaymentIntent のステータスを取得し、顧客に支払いステータスを表示できます。

return_url を指定する際に、返品ページで使用する独自のクエリパラメーターを追加することもできます。

顧客が自社のサイトにリダイレクトされたら、payment_intent_client_secret を使用して PaymentIntent をクエリし、顧客に取引ステータスを表示できます。

クエリパラメーターのいずれか 1 つを使用して PaymentIntent を取得します。PaymentIntent の ステータス を調べて、顧客に表示する内容を決定します。また、return_url を指定するときに独自のクエリパラメーターを追加することもできます。このパラメーターはリダイレクトプロセスの間を通じて存続します。

// Initialize Stripe.js using your publishable key
const stripe = Stripe(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods [immediately succeed or fail][0] upon
  // confirmation, while others first enter a `processing` status.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

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

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/webhook' do
  # You can use webhooks to receive information about asynchronous payment events.
  # For more about our webhook events, see https://stripe.com/docs/webhooks.
  webhook_secret = ENV['STRIPE_WEBHOOK_SECRET']
  payload = request.body.read
  if !webhook_secret.empty?

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

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

本番環境では、Workbench で Webhook エンドポイントを設定するか、Webhook Endpoints API を使用します。

いくつかのイベントをリッスンして、このガイドの残りのステップを完了します。サブスクリプション固有の Webhook については、サブスクリプションのイベント を確認してください。

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

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

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

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

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

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

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.
    });
}

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

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

post '/cancel-subscription' do
  content_type 'application/json'
  data = JSON.parse request.body.read

  deleted_subscription = Stripe::Subscription.cancel(data['subscriptionId'])

  deleted_subscription.to_json
end

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

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

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

支払い方法をテストする

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

イベントを監視する

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

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