Express Checkout Element で決済を受け付ける

単一の導入を使用して、ワンクリックの支払いボタンで決済を受け付けます。

Express Checkout Element は、ワンクリックの決済手段ボタンで決済を受け付ける実装です。対応している決済手段には、Link、Apple Pay、Google Pay、PayPal、Klarna、Amazon Pay などがあります。

顧客が使用するデバイスとブラウザーの組み合わせのサポート状況に応じて、表示される支払いボタンが異なります。互換性のあるデバイスでは、Google Pay と Link が自動的にサポートされます。Apple Pay と PayPal のサポートには追加のステップが必要です。

オプション	説明
加盟店の所在国	Stripe.js の初期化に使用する公開可能キーを使用して設定します。国を変更するには、Express Checkout Element のマウントを解除し、公開可能キーを更新してから、Express Checkout Element を再マウントする必要があります。
背景色	Elements Appearance API を使用して色を設定します。ボタンテーマは Appearance API から継承されますが、Element の作成時に直接定義することもできます。
デスクトップとモバイルのサイズ	ドロップダウンを使用して、Express Checkout Element がマウントされる親エレメントの最大ピクセル幅を設定します。750px (デスクトップ) または 320px (モバイル) を設定できます。
最大列数と最大行数	これらの値を設定するには、Express Checkout Element を作成するときに、layout パラメーターを使用します。
オーバーフローメニュー	これを設定するには、Express Checkout Element を作成するときに、layout パラメーターを使用します。
配送先住所を収集する	配送先情報を収集するには、Express Checkout Element の作成時にオプションを渡す必要があります。顧客の詳細情報の収集と項目の表示の詳細をご覧ください。

Express Checkout Element を使用する際は、Intent の作成前に支払いの詳細を収集することをお勧めします。これまでに Payment Element を導入している場合に、このアプローチを行うにはStripe システムの更新が必要になる場合があります。

はじめに

ブラウザーに支払い方法を追加します。たとえば、カードを Google Pay アカウントや Safari のウォレットに追加できます。
アプリケーションは HTTPS 経由で提供します。これは、開発環境と本番環境で必須です。ngrok などのサービスを利用できます。
サンドボックスと本番環境の両方でドメインを登録します。
PayPal サンドボックスアカウントを作成して、実装をテストします。

Stripe を設定する
サーバ側

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

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

支払い方法を有効にする

デフォルトでは、Stripe はお客様の決済手段の設定を使用して、Express Checkout Element ででどの決済手段を有効にするかを決定します。

有効になっている決済手段を手動で上書きするには、payment_method_types 属性を使用して、有効にする決済手段をすべてリストします。

インテントを作成する前に支払いを回収する場合は、Elementsプロバイダーオプションの paymentMethodTypes 属性に決済手段のリストを作成します。
Elements をレンダリングする前にインテントを作成する場合は、インテントの payment_method_types 属性に決済手段のリストを作成します。

サポートされている決済手段

支払い方法タイプ card を使用すると、Apple Pay と Google Pay が自動的に有効になります。Link を使用する場合は、必ず card 支払い方法タイプも渡します。

支払い方法名	Payment method API パラメーター
Apple Pay	`card`
Google Pay	`card`
Link	`link, card`
PayPal	`paypal`
Amazon Pay	`amazon_pay`
Klarna	`klarna`

Stripe Elements を設定する
クライアント側

Express Checkout 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/basil/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'
);

次に、モード (支払い、設定、またはサブスクリプション)、金額および通貨を指定して Elements のインスタンスを作成します。これらの値により、顧客に表示される支払い方法が決定されます。次のステップで、より詳細な設定が可能な Elements オプションをご覧ください。

checkout.js
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  // Customizable by using the Appearance API.
  appearance: {/*...*/},
};

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

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

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

プロパティー	タイプ	説明	必須
`mode`	`payment` `setup` `subscription`	Express Checkout Element が PaymentIntent、SetupIntent、またはサブスクリプションで使用されているかどうかを示します。	はい
`currency`	`string`	顧客に請求する金額の通貨。	はい
`amount`	`number`	Apple Pay、Google Pay、または BNPL の UI で示される、顧客に請求する金額。	`payment` および `subscription` のモードの場合
`setupFutureUsage`	`off_session` `on_session`	Express Checkout Element によって収集された決済情報を使用して、今後の支払いを行う意図を示します。Express Checkout Element を使用する PayPal または Klarna ではサポートされていません。	いいえ
`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'` とは互換性がありません。	いいえ

Express Checkout Element を作成してマウントする
クライアント側

Express Checkout Element には、HTTPS 接続を介して支払い情報を Stripe に安全に送信する iframe が含まれています。実装を機能させるには、決済ページのアドレスの先頭を http:// ではなく https:// にする必要があります。

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

checkout.html
<div id="express-checkout-element">
  <!-- Express Checkout Element will be inserted here -->
</div>
<div id="error-message">
  <!-- Display an error message to your customers here -->
</div>

フォームが読み込まれたら、Express Checkout Element のインスタンスを作成し、コンテナーの DOM ノードにマウントします。

checkout.js
// Create and mount the Express Checkout Element
const expressCheckoutElement = elements.create('expressCheckout');
expressCheckoutElement.mount('#express-checkout-element');

顧客の詳細情報を収集してラインアイテムを表示する
クライアント側

Express Checkout Element 作成時にオプションを渡します。

支払人の情報を収集する

メールアドレスを収集するには、emailRequired: true を設定して、電話番号を収集するには、phoneNumberRequired: true を設定します。billingAddressRequired はデフォルトで true です。

checkout.js
elements.create('expressCheckout', {
  emailRequired: true,
  phoneNumberRequired: true
});

PayPal の顧客情報

通常、PayPal は顧客の請求先住所 (国を除く) や電話番号を指定しません。指定されていない場合、confirm イベントでは、これらのプロパティの文字列が空になります。顧客の請求先住所または電話番号が必須である場合、Express Checkout Element は PayPal ボタンを表示しませんが、その情報を入手可能である場合を除きます。

配送先情報を収集する

shippingAddressRequired: trueを設定し、shippingRates の配列を渡します。

checkout.js
elements.create('expressCheckout', {
  shippingAddressRequired: true,
  allowedShippingCountries: ['US'],
  shippingRates: [
    {
      id: 'free-shipping',
      displayName: 'Free shipping',
      amount: 0,
      deliveryEstimate: {
        maximum: {unit: 'day', value: 7},
        minimum: {unit: 'day', value: 5}
      }
    },
  ]
});

shippingaddresschange イベントをリッスンして、顧客が配送先住所を選択した際にこれを検出します。このイベントを処理する場合は、resolve または reject のいずれかを呼び出す必要があります。

注

プライバシー確保のため、ブラウザーは配送料の計算に必要のない機密情報を削除して、配送先住所を匿名化する場合があります。国によっては、一部のフィールドが欠落していたり、部分的に非表示になっていたりすることがあります。たとえば、アメリカの配送先住所は、市、州、郵便番号のみで構成されます。ブラウザーの決済インターフェースで購入が確定されると、confirm イベントオブジェクトに配送先住所が表示されます。

checkout.js
expressCheckoutElement.on('shippingaddresschange', async (event) => {
  const response = await fetch('/calculate-shipping', {
    data: JSON.stringify({
      shippingAddress: event.address
    })
  });
  const result = await response.json();
  event.resolve({
    lineItems: result.updatedLineItems,
  });
});

shippingratechange イベントをリッスンして、顧客が配送料金を選択した際にこれを検出します。このイベントを処理する場合は、resolve または reject のいずれかを呼び出す必要があります。

checkout.js
expressCheckoutElement.on('shippingratechange', async (event) => {
  const response = await fetch('/calculate-and-update-amount', {
    data: JSON.stringify({
      shippingRate: event.shippingRate
    })
  });
  const result = await response.json();
  elements.update({amount: result.amount})
  event.resolve({
    lineItems: result.updatedLineItems,
  });
});

cancel イベントをリッスンして、顧客が決済インターフェイスを閉じた際に、これを検出します。金額を当初の金額にリセットします。

checkout.js
expressCheckoutElement.on('cancel', () => {
  elements.update({amount: 1099})
});

ラインアイテムを表示する

lineItems の配列を渡します。:

checkout.js
elements.create('expressCheckout', {
  lineItems: [
    {
      name: 'Sample item',
      amount: 1000
    },
    {
      name: 'Tax',
      amount: 100
    },
    {
      name: 'Shipping cost',
      amount: 1000
    }
  ]
});

Apple Pay インターフェイスを設定する

Apple Pay インターフェイスの設定方法をご確認ください。

加盟店が開始する取引 (MIT)

ユーザーが Apple Pay で決済する際に、Express Checkout Element click イベントで関連するマーチャントトークンのタイプをリクエストすることで、継続支払い、後払い、自動リロード支払いを設定することができます。Apple Pay マーチャントトークンを実装する際は、Apple Pay の最新ガイドラインに準拠し、将来の実装に対応できるようにすることをお勧めします。

オプションready イベントをリッスンする
クライアント側

マウント後、しばらくの間は Express Checkout Element にボタンが表示されません。ボタンを表示するときに Element をアニメーション表示するには、ready イベントをリッスンし、availablePaymentMethods の値を調べて、Express Checkout Element に表示するボタン (ある場合) を決定します。

checkout.js
// Optional: If you're doing custom animations, hide the Element
const expressCheckoutDiv = document.getElementById('express-checkout-element');
expressCheckoutDiv.style.visibility = 'hidden';

expressCheckoutElement.on('ready', ({availablePaymentMethods}) => {
  if (!availablePaymentMethods) {
    // No buttons will show
  } else {
    // Optional: Animate in the Element
    expressCheckoutDiv.style.visibility = 'initial';
  }
});

オプション支払いボタンを表示するタイミングを管理する
クライアント側

Express Checkout Element に表示する支払い方法は、次のいくつかの方法で管理できます。

Stripe ダッシュボードの支払い方法の設定。
paymentMethods property を使用して、支払いボタンを無効化します。このプロパティを使用すると、顧客に表示する内容をより細かく管理できます。

Express Checkout Element は、顧客がサポート対象のプラットフォームを使用していて、有効なカードを保有している場合に Apple Pay または Google Pay を表示します。顧客が有効なカードを保有していない場合でも、常に Apple Pay と Google Pay を表示するには、paymentMethods を使用してこれを設定することもできます。

オプションボタンのスタイルを設定する
クライアント側

支払い方法の各ボタンのスタイルを個別に設定できます。ボタンのテーマとタイプの例については、Google Pay と Apple Pay のリソースをご確認ください。borderRadius 変数は、Appearance API で使用することもできます。

checkout.js
const appearance = {
  variables: {
    // This controls the border-radius of the rendered Express Checkout Element
    borderRadius: '4px',
  }
};

// Pass the appearance object to the Elements instance
const elements = stripe.elements({clientSecret, appearance});

elements.create('expressCheckout', {
  // Specify a type per payment method
  // Defaults to 'buy' for Google, 'plain' for Apple, and 'paypal' for PayPal
  buttonType: {
    googlePay: 'checkout',
    applePay: 'check-out',
    paypal: 'buynow',
  },
  // Specify a theme per payment method
  // Default theme is based on appearance API settings
  buttonTheme: {
    applePay: 'white-outline'
  },
  // Height in pixels. Defaults to 44. The width is always '100%'.
  buttonHeight: 55
});

オプションConfirmationToken を作成する
クライアント側

支払いが顧客によって承認されると、ConfirmationToken を作成できます。追加の検証またはビジネスロジックのために、確定前にこれをサーバーに送信します。作成された ConfirmationToken をすぐに使用して、PaymentIntent または SetupIntent を確定する必要があります。

checkout-confirmation.js
const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
}

expressCheckoutElement.on('confirm', async (event) => {
  ...

  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create a ConfirmationToken using the details collected by the Express Checkout Element
  const {error, confirmationToken} = await stripe.createConfirmationToken({
    elements,
    params: {
      payment_method_data: {
        billing_details: {
          name: 'Jenny Rosen',
        }
      },
      return_url: 'https://example.com/order/123/complete'
    }
  });

  if (error) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
    return;
  }

  // Send the ConfirmationToken ID to your server for additional logic and attach the ConfirmationToken
  const res = await fetch('/create-intent', {
    method: 'POST',
    body: confirmationToken.id
  });
  const {client_secret: clientSecret} = await res.json();

  // Confirm the PaymentIntent
  const {error: confirmError} = await stripe.confirmPayment({
    clientSecret,
    confirmParams: {
      confirmation_token: confirmationToken.id
    },
  });

  if (confirmError) {
    // This point is only reached if there's an immediate error when
    // confirming the payment. Show the error to your customer (for example, payment details incomplete)
    handleError(confirmError);
  } else {
    // The payment UI automatically closes with a success animation.
    // Your customer is redirected to your `return_url`.
  }
});

PaymentIntent を作成する
サーバー側

Stripe は PaymentIntent オブジェクトを使用して、顧客から支払いを回収するお客様の意図を示し、プロセス全体を通して請求の実施と支払い状態の変化を追跡します。

サーバーで金額と通貨を指定し、PaymentIntent を作成します。これは、ステップ 3 で stripe.elements インスタンスに設定した内容と一致している必要があります。請求金額は、クライアント側ではなく、常に信頼できる環境のサーバー側で指定してください。これにより、悪意のある顧客が金額を恣意的に選択できないようにします。

返される PaymentIntent には client secret が含まれています。これは、PaymentIntent オブジェクト全体を渡すことなく安全に決済プロセスを完了するために、クライアント側で使用されます。client secret をクライアント側に渡す際には、いくつかの方法を使用できます。

Stripe に支払いを送信する
クライアント側

stripe.confirmPayment を使用し、Express Checkout Element からの詳細を使って支払いを完了します。

注

Amazon Pay、Klarna、PayPal の場合、PaymentIntent で確定した金額と買い手が事前承認した金額が一致している必要があります。金額が一致しないと、支払いは拒否されます。

支払いの完了後に Stripe がユーザーをリダイレクトする場所を指定するには、この関数に return_url を指定します。ユーザーは、最初に中間サイトにリダイレクトされてから、return_url にリダイレクトされる場合があります。支払いが正常に完了するとすぐに return_url にリダイレクトされます。

支払いの完了後にリダイレクトを行わない場合は、redirect を if_required に設定します。これで、リダイレクトベースの支払い方法で購入する顧客のみがリダイレクトされます。

checkout.js
const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
}

expressCheckoutElement.on('confirm', async (event) => {
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the PaymentIntent and obtain clientSecret
  const res = await fetch('/create-intent', {
    method: 'POST',
  });
  const {client_secret: clientSecret} = await res.json();

  const {error} = await stripe.confirmPayment({
    // `elements` instance used to create the Express Checkout Element
    elements,
    // `clientSecret` from the created PaymentIntent
    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 payment. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
  } else {
    // The payment UI automatically closes with a success animation.
    // Your customer is redirected to your `return_url`.
  }
});

実装をテストする

本番環境に移行する前に、各支払い方法の組み込みをテストします。支払い方法のブラウザーとの互換性を判断するには、サポートされるブラウザーをご覧ください。iframe で Express Checkout Element を使用している場合、iframe で allow 属性を payment * に設定する必要があります。

注意

サンドボックスの Link アカウントには実際のユーザーデータを保存しないでください。これらのテストアカウントは公開可能キーに関連付けられているため、公開されるものとして扱ってください。

Link は現在、クレジットカード、デビットカード、および資格要件を満たしたアメリカの銀行口座からの購入にのみ対応しています。Link では、ドメインの登録が必要です。

有効なメールアドレスを使用して、Link のサンドボックスアカウントを作成できます。次の表は、Stripe がサンドボックスアカウントの認証に使用できる共通のワンタイムパスコードの値を示しています。

値	結果
以下に記載されていない任意の 6 桁の数字	成功
000001	エラー: コードが無効です
000002	エラー: コードの有効期限が切れています
000003	エラー: 最大試行回数を超えました

オプションStripe Connect で Express Checkout Element を使用する

連結アカウントの Customer に対してダイレクト支払いの作成や、トークンの追加を行う Connect プラットフォームでは、追加のステップを実行する必要があります。

フロントエンドで、ExpressCheckoutElement を作成する前に、Stripe インスタンスで stripeAccount オプションを設定します。

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
, {
  apiVersion: "2025-08-27.basil",
  stripeAccount: '{{CONNECTED_ACCOUNT_ID}}'
,
});

Express Checkout Element を表示する予定のすべてのドメインを登録します。

顧客に Stripe を開示する

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

注

Express Checkout Element で決済を受け付ける

単一の導入を使用して、ワンクリックの支払いボタンで決済を受け付けます。

はじめに

Stripe を設定するサーバ側

支払い方法を有効にする

サポートされている決済手段

Stripe Elements を設定するクライアント側

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

Express Checkout Element を作成してマウントするクライアント側

顧客の詳細情報を収集してラインアイテムを表示するクライアント側