# Express Checkout Element に移行する

支払いリクエストボタン Element を利用する既存の連携を、Express Checkout Element の利用に移行します。

[支払いリクエストボタンエレメント](https://docs.stripe.com/stripe-js/elements/payment-request-button.md) を使用すると、[Apple Pay](https://docs.stripe.com/apple-pay.md),[Google Pay](https://docs.stripe.com/google-pay.md), または[Link](https://docs.stripe.com/payments/link.md) によるカード決済を受け付けることができます。[Express Checkout Element](https://docs.stripe.com/elements/express-checkout-element.md) に移行すると、[PayPal](https://docs.stripe.com/payments/paypal.md) を含む 1 つまたは複数の支払いボタンで、カードまたは[ウォレット](https://docs.stripe.com/payments/wallets.md) による決済を受け付けることができます。

| 既存のシステムで使用している機能                                                                                | 手順                                                                                                      |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [Payment Intents](https://docs.stripe.com/api/payment_intents.md) API を決済の作成と追跡や決済時のカード詳細の保存に使用 | Express Checkout Element を使用するにはこのガイドの手順に従います。                                                          |
| [Charges](https://docs.stripe.com/api/charges.md) API (トークンを使用)                                 | 先に進む前に [Payment Intents API](https://docs.stripe.com/payments/payment-intents/migration.md#web) に移行します。 |

## 支払い方法を有効にする

[支払い方法の設定](https://dashboard.stripe.com/settings/payment_methods)で、サポートする支払い方法を有効にしてください。少なくとも 1 つの支払い方法を有効にする必要があります。

デフォルトでは、カード支払いとその他の一般的な支払い方法が有効になっています。企業と顧客に適した追加の支払い方法を有効にできます。プロダクトと決済手段のサポートについては、Stripe の[決済手段のサポート](https://docs.stripe.com/payments/payment-methods/payment-method-support.md)を、手数料については[料金体系ページ](https://stripe.com/pricing/local-payment-methods)をご覧ください。

## Elements インスタンスを更新する [クライアント側]

次に、モード (決済)、金額、通貨を渡すようにクライアント側のコードを更新します。これらの値により、顧客に表示する支払い方法が決定されます。

たとえば、`PaymentIntent` で `eur` 通貨を渡し、ダッシュボードで OXXO を有効にしても、OXXO は `eur` の決済をサポートしないため、顧客に表示されません。

Stripe は、通貨、支払い方法の制限、その他のパラメーターを評価して、対応可能な支払い方法のリストを決定します。コンバージョン率上昇につながり、使用通貨と顧客の所在地に最も適した支払い方法が優先的に表示されます。

#### HTML + JS

### Before

```javascript
const stripe =
    Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const elements = stripe.elements();
```

### After

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
};
const elements = stripe.elements(options);
```

#### React

### Before

```jsx
 const stripePromise =
     loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

 function App() {
  return (
    <Elements stripe={stripePromise}>
      <CheckoutForm />
    </Elements>
  );
};
```

### After

```jsx
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
};

function App() {
  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};
```

## Optional: 支払い中に支払いの詳細を保存する

既存の実装で決済中にカード詳細を保存している場合は、`setup_future_usage` オプションを`stripe.confirmCardPayment` による決済の確定ステージで 渡すのではなく、Elements インスタンスの作成時にこのオプションを使用します。

一部の支払い方法は、決済時に保存できません。これらの[支払い方法](https://docs.stripe.com/payments/payment-methods/integration-options.md)も他のユースケース用に有効にできますが、将来の決済に備えた設定時にオプションとして顧客に表示されることはありません。

#### HTML + JS

```javascript
const stripe = Stripe('<<YOUR_PUBLISHABLE_KEY>>');
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',setup_future_usage: 'off_session',
};
const elements = stripe.elements(options);
```

#### React

```jsx
const stripePromise = loadStripe('<<YOUR_PUBLISHABLE_KEY>>');

const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',setup_future_usage: 'off_session',
};

function App() {
  return (
    <Elements stripe={stripePromise} options={options}>
      <CheckoutForm />
    </Elements>
  );
};
```

## PaymentIntent 作成コールを更新する [サーバー側]

`PaymentIntent` には購入時に買い手に表示される支払い方法が含まれます。支払い方法は[ダッシュボード](https://dashboard.stripe.com/settings/payment_methods)で管理できます。Stripe は取引額、通貨、決済フローなどの要素に基づいて、適切な支払い方法が返されるように処理します。

#### curl

```bash
curl https://api.stripe.com/v1/payment_intents \
  -u <<YOUR_SECRET_KEY>>: \
  -H "Stripe-Version: 2026-02-25.clover" \
  -d "amount"=1099 \
  -d "currency"="usd" \-d "automatic_payment_methods[enabled]"=true \
```

既存の実装が複数の支払い方法に対応している場合や、カード以外の支払い方法を受け付ける必要がある場合は、ダッシュボードで[有効にする支払い方法を追加する](https://dashboard.stripe.com/settings/payment_methods)ことができます。

## Express Checkout Element を追加する [クライアント側]

[React Stripe.js](https://github.com/stripe/react-stripe-js) を使用する場合、Express Checkout Element を使用するには最新のパッケージに更新してください。

支払いリクエストボタン Element を Express Checkout Element に置き換えます。`PaymentRequestButtonElement` を `ExpressCheckoutElement` に置き換える方法の例を以下に示します。

`paymentRequest` オブジェクトを作成する必要がなくなりました。代わりに、`ExpressCheckoutElement` の作成時にオプションを渡します。

#### HTML + JS

### Before

```html
<div id="payment-request-button">
</div>
```

### After

```html
<div id="express-checkout-element">
  <!-- Mount the Express Checkout Element here -->
</div>
```

### Before

```javascript
const paymentRequest = stripe.paymentRequest({
  country: 'US',
  currency: 'usd',
  total: {
    label: 'Demo total',
    amount: 1099,
  },
  requestPayerName: true,
  requestPayerEmail: true,
});
const paymentRequestButton = elements.create('paymentRequestButton', {
  paymentRequest: paymentRequest,
});
paymentRequestButton.mount("#payment-request-button");
paymentRequest.canMakePayment().then(function(result) {
  if (result) {
    prButton.mount('#payment-request-button');
  } else {
    document.getElementById('payment-request-button').style.display = 'none';
  }
});
```

### After

```javascript
const expressCheckoutElement = elements.create("expressCheckout", {
  emailRequired: true
});
expressCheckoutElement.mount("#express-checkout-element");
```

#### React

### Before

```jsx
import React, {useState, useEffect} from 'react';
import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const stripe = useStripe();
  const [paymentRequest, setPaymentRequest] = useState(null);

  useEffect(() => {
    if (stripe) {
      const pr = stripe.paymentRequest({
        country: 'US',
        currency: 'usd',
        total: {
          label: 'Demo total',
          amount: 1099,
        },
        requestPayerName: true,
        requestPayerEmail: true,
      });

      pr.canMakePayment().then(result => {
        if (result) {
          setPaymentRequest(pr);
        }
      });
    }
  }, [stripe]);

  return (
    paymentRequest && <PaymentRequestButtonElement options={{paymentRequest}} />
  );
}
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const options = {
    emailRequired: true
  };

  return (
    <div id="checkout-page">
      <ExpressCheckoutElement
        options={options}
        onConfirm={onConfirm}
      />
    </div>
  );
};
```

## Optional: Apple Pay マーチャントトークン (MPAN) をリクエストする

Express Checkout Element は Apple Pay トークンをサポートとしているため、デバイストークンではなく、Apple Pay マーチャントトークンを使用して、継続支払い、後払い、自動リロード支払いなど加盟店が開始する取引 (MIT) を有効化することをお勧めします。マーチャントトークン (MPAN) は自社と顧客の Apple ウォレット支払い方法を接続するので、MPAN は複数のデバイスで機能し、支払い情報が紛失または盗難されたデバイスから削除された場合でも、新しいデバイスで有効な状態が維持されます。実装について、詳細は [Apple Pay マーチャントトークン](https://docs.stripe.com/apple-pay/merchant-tokens.md?pay-element=ece)をご覧ください。

## Optional: ready イベントをリッスンする

マウント後、しばらくの間は Express Checkout Element にボタンが表示されません。ボタンを表示するときに Element にアニメーションを表示することができます。そのためには、[ready イベント](https://docs.stripe.com/js/element/events/on_ready)をリッスンし、`availablePaymentMethods` の値を調べて、Express Checkout Element に表示するボタン (ある場合) を決定します。

#### HTML + JS

```javascript
// 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';
  }
});
```

#### React

```jsx
import React, {useState} from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';
import {onConfirm} from './confirmHandler';

const CheckoutPage = () => {
  // Optional: If you're doing custom animations, hide the Element
  const [visibility, setVisibility] = useState('hidden');
const onReady = ({availablePaymentMethods}) => {
    if (!availablePaymentMethods) {
      // No buttons will show
    } else {
      // Optional: Animate in the Element
      setVisibility('initial');
    }
  };

  return (
    <div id="checkout-page">
      <div id="express-checkout-element" style={{visibility}}>
        <ExpressCheckoutElement
          onConfirm={onConfirm}onReady={onReady}
        />
      </div>
    </div>
  );
};
```

## Optional: Express Checkout Element のスタイルを設定する

支払い方法のボタン ([Google Pay](https://developers.google.com/pay/api/web/guides/resources/customize) や [Apple Pay](https://developer.apple.com/design/human-interface-guidelines/technologies/apple-pay/buttons-and-marks/) など) は、個別に[スタイルを設定](https://docs.stripe.com/js/elements_object/create_express_checkout_element#express_checkout_element_create-options-buttonTheme)して、さまざまなテーマとタイプを指定できます。

[Appearance](https://docs.stripe.com/elements/appearance-api.md?platform=web#commonly-used-variables) API の `borderRadius` 変数も使用できます。

#### HTML + JS

### Before

```javascript
elements.create('paymentRequestButton', {
  paymentRequest,
  style: {
    paymentRequestButton: {
      type: 'book',
      theme: 'dark',
      height: '55px',
    },
  },
});
```

### After

```javascript
const appearance = {
  variables: {
    // This controls the border-radius of the rendered Express Checkout Element.
    borderRadius: '4px',
  }
};
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  appearance,
};
// Pass the appearance object to the Elements instance.
const elements = stripe.elements({options});
elements.create('expressCheckout', {
  layout: 'auto',
  buttonType: {
    googlePay: 'book',
    applePay: 'book',
    paypal: 'buynow',
  },
  buttonTheme: {
    applePay: 'black'
  },
  buttonHeight: 55
});
```

#### React

### Before

```jsx
import React, {useState, useEffect} from 'react';
import {PaymentRequestButtonElement, useStripe} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const options = {
    paymentRequest,
    style: {
      paymentRequestButton: {
        type: 'book',
        theme: 'dark',
        height: '55px',
      },
    }
  };

  return <PaymentRequestButtonElement options={options} />;
}
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const options = {
    layout: 'auto',
    buttonType: {
      googlePay: 'book',
      applePay: 'book',
      paypal: 'buynow',
    },
    buttonTheme: {
      applePay: 'black'
    },
    buttonHeight: 55
  }

  return (
    <ExpressCheckoutElementoptions={options}
      onConfirm={onConfirm}
    />
  );
};
```

## 支払いの確定方法を更新する [クライアント側]

[confirm](https://docs.stripe.com/js/elements_object/express_checkout_element_confirm_event) イベントをリッスンして、確定を処理します。決済情報を収集して Stripe に送信するには、`stripe.confirmCardPayment` などの個別の確定メソッドではなく、[stripe.confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) を使用します。

`stripe.confirmPayment` は、PaymentMethod ID ではなく、Express Checkout Element の Elements インスタンスと、作成した `PaymentIntent` の client secret を使用します。

`stripe.confirmPayment` は、呼び出されると、3DS ダイアログを表示するか、または銀行の承認ページへ顧客をリダイレクトして顧客認証を行うなどして、必要なアクションを実行しようとします。確認が完了すると、ユーザーは、構成されている [return_url](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-return_url) に移動します。これは、決済のステータスを表示するウェブサイトのページに対応しています。

カード支払いの決済フローで、必要な場合にのみリダイレクトを行うようにする場合、[redirect](https://docs.stripe.com/js/payment_intents/confirm_payment#confirm_payment_intent-options-redirect) に `if_required` を設定できます。これは、Express Checkout Element には適用されません。

`stripe.confirmCardPayment` を `stripe.confirmPayment` に置き換える例を以下に示します。

#### HTML + JS

### Before

```javascript
paymentRequest.on('paymentmethod', function(ev) {
  stripe.confirmCardPayment(
    '{{CLIENT_SECRET}}',
    {payment_method: ev.paymentMethod.id},
    {handleActions: false}
  ).then(function(confirmResult) {
    if (confirmResult.error) {
      ev.complete('fail');
    } else {
      ev.complete('success');
      if (confirmResult.paymentIntent.status === "requires_action") {
        stripe.confirmCardPayment(clientSecret).then(
          function(result) {
            if (result.error) {
              // The payment failed -- ask your customer for a new payment method.
            } else {
              // The payment succeeded.
            }
          }
        );
      } else {
        // The payment succeeded.
      }
    }
  });
});
```

### After

```javascript
expressCheckoutElement.on('confirm', async (event) => {
  const {error} = await stripe.confirmPayment({
    // `Elements` instance that's used to create the Express Checkout Element.
    elements,
    // `clientSecret` from the created PaymentIntent
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
    // Uncomment below if you only want redirect for redirect-based payments.
    // redirect: 'if_required',
  });

  if (error) {
    // This point is reached only if there's an immediate error when confirming the payment. Show the error to your customer (for example, payment details incomplete).
  } else {
    // Your customer will be redirected to your `return_url`.
  }
});
```

#### React

### Before

```javascript
paymentRequest.on('paymentmethod', function(ev) {
  stripe.confirmCardPayment(
    '{{CLIENT_SECRET}}',
    {payment_method: ev.paymentMethod.id},
    {handleActions: false}
  ).then(function(confirmResult) {
    if (confirmResult.error) {
      ev.complete('fail');
    } else {
      ev.complete('success');
      if (confirmResult.paymentIntent.status === "requires_action") {
        stripe.confirmCardPayment(clientSecret).then(
          function(result) {
            if (result.error) {
              // The payment failed -- ask your customer for a new payment method.
            } else {
              // The payment succeeded.
            }
          }
        );
      } else {
        // The payment succeeded.
      }
    }
  });
});
```

### After

```jsx
import React from 'react';
import {ExpressCheckoutElement} from '@stripe/react-stripe-js';

const CheckoutPage = () => {
  const onConfirm = () => {
    const {error} = await stripe.confirmPayment({
      // `Elements` instance that's used to create the Express Checkout Element.
      elements,
      // `clientSecret` from the created PaymentIntent
      clientSecret,
      confirmParams: {
        return_url: 'https://example.com/order/123/complete',
      },
      // Uncomment below if you only want redirect for redirect-based payments.
      // redirect: 'if_required',
    });

    if (error) {
      // This point is reached only if there's an immediate error when confirming the payment. Show the error to your customer (for example, payment details incomplete).
    } else {
      // Your customer will be redirected to your `return_url`.
    }
  };

  return (
    <div id="checkout-page">
      <ExpressCheckoutElementonConfirm={onConfirm}
      />
    </div>
  );
};
```

## 支払い後のイベントを処理する [サーバー側]

支払いが完了すると、Stripe は [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) イベントを送信します。[ダッシュボードの Webhook ツール](https://dashboard.stripe.com/webhooks)を使用するか [Webhook のガイド](https://docs.stripe.com/webhooks/quickstart.md)に従ってこれらのイベントを受信し、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行します。

クライアントからのコールバックを待つのではなく、これらのイベントをリッスンします。クライアントでは、コールバックが実行される前に顧客がブラウザーのウィンドウを閉じたり、アプリを終了する場合、また悪意を持つクライアントがレスポンスを不正操作する場合もあります。非同期型のイベントをリッスンするよう組み込みを設定すると、単一の組み込みで[複数の異なるタイプの支払い方法](https://stripe.com/payments/payment-methods-guide)を受け付けることができます。

Payment Element を使用して支払いを回収する場合は、`payment_intent.succeeded` イベントのほかにこれらのイベントを処理することをお勧めします。

| イベント                                                                                                                            | 説明                                                                                                                                                                       | アクション                                                                                                                                                              |
| ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.succeeded)           | 顧客が正常に支払いを完了したときに送信されます。                                                                                                                                                 | 顧客に注文の確定を送信し、顧客の注文の*フルフィルメント* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected)を実行します。 |
| [payment_intent.processing](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.processing)         | 顧客が正常に支払いを開始したが、支払いがまだ完了していない場合に送信されます。このイベントは、多くの場合、顧客が口座引き落としを開始するときに送信されます。その後、`payment_intent.succeeded` イベント、また、失敗の場合は `payment_intent.payment_failed` イベントが送信されます。 | 顧客に注文確認メールを送信し、支払いが保留中であることを示します。デジタル商品では、支払いの完了を待たずに注文のフルフィルメントを行うことが必要になる場合があります。                                                                                |
| [payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md?lang=php#event_types-payment_intent.payment_failed) | 顧客が支払いを試みたが、支払いに失敗する場合に送信されます。                                                                                                                                           | 支払いが `processing` から `payment_failed` に変わった場合は、顧客に再度支払いを試すように促します。                                                                                                 |