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

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

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

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

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

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

新しい顧客がプランを選択してからサブスクリプションを作成できるようにします。このガイドでは、顧客は基本またはプレミアムから選択します。

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

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

バックエンドで、payment_behavior=default_incomplete を使用して、ステータスが incomplete のサブスクリプションを作成します。次に、サブスクリプションの最初の支払いインテントの 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/basil/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 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 の設定

• お客様のサイトのデザインに合わせて Payment Element をカスタマイズする場合、Elements のインスタンスを作成する際に Appearance オブジェクトを options に渡します。
• 継続支払い、自動再読み込み、後払いに対応するために、マーチャントトークンを返すよう 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 will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected 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 will [immediately succeed or fail][0] upon
  // confirmation, while others will 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 から送信される webhooks を処理する必要があります。これらのイベントは、サブスクリプションの新しい請求書が生成されるなど、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 check out 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

For production, set up a webhook endpoint in Workbench, or use the 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 のステータスになります。または、お客様が customer portal を実装している場合、顧客はお客様のアプリケーションに直接アクセスせずにサブスクリプションをキャンセルする可能性があります。ハンドラーを正しく実装することで、お客様のアプリケーションのステータスを 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 で表示できます。

詳しくは、Billing の導入テストをご覧ください。