インテントを作成する前に支払いの詳細を収集する

PaymentIntent または SetupIntent を作成する前に Payment Element をレンダリングできるシステムを構築します。

Customers v1 と Accounts v2 のリファレンスを比較する

顧客が Accounts v2 の事業体に該当する場合は、ガイドを参照して、コード内の Customer とイベントの参照先を同等の Accounts v2 API リファレンスに置き換えてください。

サブスクリプションは、ユーザーが商品を利用するために継続的に支払う料金体系モデルです。この導入ガイドでは、Payment Element をレンダリングして、サブスクリプションを作成し、顧客のブラウザーから決済を確定できるカスタムの決済フローを作成する方法をご紹介します。

Stripe を設定する
サーバ側

まず、Stripe アカウントを作成するかサインインします。

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

支払い方法を有効にする

注意

この導入パスは、Automated Clearing Settlement System (ACSS) を使用する BLIK またはプレオーソリデビットに対応していません。

支払い方法の設定を表示して、サポートする支払い方法を有効にします。PaymentIntent を作成するには、少なくとも 1 つは支払い方法を有効にする必要があります。

多くの顧客から決済を受け付けられるよう、Stripe では、カードやその他一般的な決済手段がデフォルトで有効になっていますが、ビジネスや顧客に適した追加の決済手段を有効にすることをお勧めします。プロダクトと決済手段のサポートについては決済手段のサポートを、手数料については料金体系ページをご覧ください。

サブスクリプションの場合、請求書設定と、サポートされる支払い方法を設定します。不一致や誤りがないように、請求書設定は Payment Element 設定と一致している必要があります。

支払いの詳細を収集する
クライアント側

Payment Element を使用して、iFrame で収集された支払い情報を HTTPS 接続で安全に Stripe に送信します。

iFrame の競合

Payment Element を別の iframe 内に配置しないでください。支払い確認のために別のページにリダイレクトする必要がある支払い方法と競合します。

構築済みのシステムを機能させるには、決済ページの URL の先頭を https:// rather ではなく http:// for にする必要があります。HTTPS を使用しなくても導入をテストできますが、本番環境で決済を受け付ける準備が整ったら、必ず HTTPS を有効にしてください。

Stripe.js を設定する

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

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

購入ページで次の JavaScript を使用して、Stripe のインスタンスを作成します。

checkout.js
// 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 ノード (コンテナー) を作成します。

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

フォームが読み込まれたら、モード、金額、通貨を指定して Elements インスタンスを作成します。これらの値から、Element が顧客に表示する支払い方法が決定されます。

次に、Payment Element のインスタンスを作成し、コンテナーの DOM ノードにマウントします。

メモ

Payment Element に渡される amount は、顧客がすぐに請求される内容を反映している必要があります。サブスクリプションの初回の分割払いのほか、サブスクリプションにトライアル期間が設定されている場合には 0 が示される場合があります。

checkout.js
const options = {
  mode: 'subscription',
  amount: 1099,
  currency: 'usd',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form
const elements = stripe.elements(options);

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

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

Elements プロバイダーを作成する際に Appearance (デザイン) オブジェクトを options に渡すことで、サイトのデザインに合わせて Payment Element をカスタマイズできます。

住所を収集

デフォルトでは、Payment Element は必要な請求住所の詳細のみを収集します。税金の計算、配送先情報を入力するなどの一部の動作では、顧客の完全な住所が必要です。次のように対応できます。

Address Element を使用して、オートコンプリートとローカリゼーションの機能を利用して、顧客の完全な住所を収集します。これにより、最も正確な税金計算が可能になります。
独自のカスタムフォームを使用して住所の詳細を収集する。

オプションレイアウトをカスタマイズする
クライアント側

決済フローインターフェイスに合わせて Payment Element のレイアウト (アコーディオンまたはタブ) をカスタマイズできます。各プロパティについて、詳細は elements.create をご覧ください。

Payment Element の作成時にレイアウトの type と他のオプションプロパティーを渡すと、レイアウト機能の使用を開始できます。

const paymentElement = elements.create('payment', {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: true,
    spacedAccordionItems: false
  }
});

以下の画像は、異なるレイアウト設定を適用した同一 Payment Element の表示を示しています。

Payment Element のレイアウト

オプションデザインをカスタマイズする
クライアント側

これで、Payment Element がページに追加されました。次は、デザインに合わせて外観をカスタマイズできます。Payment Element のカスタマイズについての詳細は、Elements Appearance API をご覧ください。

Payment Element をカスタマイズする

オプション顧客の支払い方法を保存および取得する

将来の利用に備えて顧客の決済手段を保存するように Payment Element を設定できます。このセクションでは、決済手段の保存機能を導入する方法を説明しています。Payment Element で以下を実行できます。

買い手に支払い方法を保存することの同意を求める
買い手が同意した場合に支払い方法を保存する
将来の購入時に保存した支払い方法を買い手に表示する
買い手が紛失したカードまたは期限切れのカードを交換するときにそれらのカードを自動的に更新する

決済手段を保存します。

以前に保存した支払い方法を再利用します。

Payment Element で支払い方法の保存機能を有効にする

サーバー側で CustomerSession を作成します。その際、Customer ID を指定して、セッションの payment_element コンポーネントを有効にします。有効にする保存済みの決済手段機能を設定します。たとえば、payment_method_save を有効にすると、将来使用できるように支払いの詳細を保存するためのチェックボックスが、顧客に表示されます。

PaymentIntent または Checkout セッションで setup_future_usage を指定して、決済手段を保存するためのデフォルトの動作を上書きできます。これにより、顧客が明示的に保存を選択しなくても、将来の使用に備えて決済手段を自動的に保存できます。

注意

payment_method_remove を有効にして、保存済みの決済手段を買い手が削除できるようにすると、その決済手段を利用しているサブスクリプションに影響します。決済手段を削除すると、PaymentMethod とその Customer の関連付けが解除されます。

Elements インスタンスはその CustomerSession の client secret を使用して、顧客が保存した支払い方法にアクセスします。CustomerSession の作成時に適切にエラーを処理します。エラーが発生した場合、CustomerSession の client secret はオプションなので、Elements インスタンスに指定する必要はありません。

CustomerSession の client secret を使用して Elements インスタンスを作成します。次に、Elements インスタンスを使用して、Payment Element を作成します。

checkout.js
// Create the CustomerSession and obtain its clientSecret
const res = await fetch("/create-customer-session", {
  method: "POST"
});

const {
  customer_session_client_secret: customerSessionClientSecret
} = await res.json();

const elementsOptions = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  customerSessionClientSecret,
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret
// and CustomerSession's client secret obtained in a previous step
const elements = stripe.elements(elementsOptions);

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

PaymentIntent の確定時に、顧客が支払いの詳細を保存するためのボックスにチェックマークを付けたかどうかに応じて、Stripe.js が PaymentIntent の setup_future_usage および allow_redisplay の設定をコントロールします。

セキュリティコードの再収集を実行する

オプションとして、PaymentIntent の作成時と Elements の作成時の両方に require_cvc_recollection を指定して、顧客がカードで支払う場合にセキュリティコードの再収集を実行します。

保存した支払い方法の選択内容を検出する

保存した支払い方法を選択したときにコンテンツを動的に制御するには、Payment Element の change イベントをリッスンします。このイベントには、選択した支払い方法の情報が入力されています。

checkout.js
paymentElement.on('change', function(event) {
  if (event.value.payment_method) {
    // Control dynamic content if a saved payment method is selected
  }
})

オプション追加の Elements オプション
クライアント側

Elements オブジェクトは、支払いの回収に影響する追加オプションを受け入れます。指定したオプションを基に Payment Element は、有効化した決済手段の中から利用可能なものを表示します。詳しくは、決済手段のサポートをご覧ください。

プロパティー	タイプ	説明	必須
`mode`	`payment` `setup` `subscription`	Payment Element が PaymentIntent、SetupIntent、またはサブスクリプションで使用されているかどうかを示します。	はい
`currency`	`string`	顧客に請求する金額の通貨。	はい
`amount`	`number`	Apple Pay、Google Pay、または BNPL の UI で示される、顧客に請求する金額。	`payment` および `subscription` のモードの場合
`setupFutureUsage`	`off_session` `on_session`	Payment Element によって収集された決済の詳細を使用して、今後の決済を行う意図を示します。	いいえ
`captureMethod`	`automatic` `automatic_async` `manual`	顧客の口座から売上をキャプチャーするタイミングを管理します。	いいえ
`onBehalfOf`	`string`	Connect のみ。取引に関する金銭的責任を負う Stripe アカウント ID。このオプションが実装に関連するかを判断するには、ユースケースをご覧ください。	いいえ
`paymentMethodTypes`	`string[]`	表示する決済手段タイプのリスト。この属性を省略して、Stripe ダッシュボードで決済手段を管理できます。	いいえ
`paymentMethodConfiguration`	`string`	Stripe ダッシュボードで決済手段を管理するときに使用する決済手段の設定。指定しない場合は、既定の構成が使用されます。	いいえ
`paymentMethodCreation`	`manual`	stripe.createPaymentMethod を使用して、Elements インスタンスから PaymentMethods が作成されるようにします。	いいえ
`paymentMethodOptions`	`{us_bank_account: {verification_method: string}}`	`us_bank_account` 決済手段の確認オプション。Payment Intents と同じ確認手段を受け入れます。	いいえ
`paymentMethodOptions`	`{card: {installments: {enabled: boolean}}}`	Stripe ダッシュボードで決済手段を管理していないときに、カード分割払いプランの選択 UI を手動で有効化できるようにします。`mode='payment'` を設定し、「さらに」`paymentMethodTypes` を明示的に指定する必要があります。それ以外の場合は、エラーが発生します。`paymentMethodCreation='manual'` とは互換性がありません。	いいえ

料金体系モデルを作成する
Stripe CLI またはダッシュボード

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

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

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

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

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

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

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

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

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

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

register.html
<form id="signup-form">
  <label>
    Email
    <input id="email" type="text" 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 オブジェクトを作成します。

サブスクリプションを作成する
サーバー側

顧客が決済フォームを送信したときに、サブスクリプションを使用して確認と決済のプロセスを円滑にします。サブスクリプションを作成するには、顧客と価格が必要です。

メモ

多通貨の価格を使用している場合、currency (通貨) パラメーターを使用して、サブスクリプションに使用する Price の通貨を指定します (currency パラメーターを省略すると、サブスクリプションは Price のデフォルトの通貨を使用します)。

サブスクリプションには、client secret が含まれています。この値をクライアントに返し、Stripe.js がこれを使用して決済プロセスを安全に完了できるようにします。事前に支払いを回収しないサブスクリプション (無料トライアル期間があるサブスクリプションなど) では、pending_setup_intent からの client secret を使用します。

サブスクリプションを確定する
クライアント側

stripe.confirmPayment、または stripe.confirmSetup を使用し、Payment Element の詳細を指定してサブスクリプションを確定します。confirm 関数に return_url を指定して、確定後に Stripe が顧客をリダイレクトする場所を示します。支払い方法によっては、顧客が return_url にリダイレクトされる前に発行会社/銀行のオーソリページなどの中間サイトにリダイレクトされます。 redirect を if_required に設定すると、リダイレクトベースの支払い方法で購入する顧客のみをリダイレクトできます。

checkout.js
const form = document.getElementById('payment-form');
const submitBtn = document.getElementById('submit');

const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
  submitBtn.disabled = false;
}

form.addEventListener('submit', async (event) => {
  // We don't want to let default form submission happen here,
  // which would refresh the page.
  event.preventDefault();

  // Prevent multiple form submissions
  if (submitBtn.disabled) {
    return;
  }

  // Disable form submission while loading
  submitBtn.disabled = true;

  // Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the subscription
  const res = await fetch('/create-subscription', {
    method: "POST",
  });
  const {type, clientSecret} = await res.json();
  const confirmIntent = type === "setup" ? stripe.confirmSetup : stripe.confirmPayment;

  // Confirm the Intent using the details collected by the Payment Element
  const {error} = await confirmIntent({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point is only reached if there's an immediate error when confirming the Intent.
    // Show the error to your customer (for example, "payment details incomplete").
    handleError(error);
  } else {
    // Your customer is redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer is redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

サブスクリプションを管理する

導入を完成するには、以下を実行します。

Webhook をリッスンする
サービスへのアクセスを提供する
顧客によるサブスクリプションのキャンセルを許可する

詳細については、サブスクリプションの実装を構築するをご覧ください。

参照情報

導入方法の設計

メモ