Express Checkout Element に移行する

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

Payment Request Button Element では、Apple Pay、Google Pay、または Link を使用したカード支払いのみを受け付けることができます。Express Checkout Element に移行すると、PayPal などの 1 つ以上の支払いボタンでカードやウォレットによる決済を受け付けることができます。詳細については、比較ガイドをご覧ください。

既存のシステムで使用している機能	手順
Payment Intents API を決済の作成と追跡や決済時のカード詳細の保存に使用	Express Checkout Element を使用するにはこのガイドの手順に従います。
Charges API (トークンを使用)	先に進む前に Payment Intents API に移行します。

支払い方法を有効にする

支払い方法の設定で、サポートする支払い方法を有効にしてください。少なくとも 1 つの支払い方法を有効にする必要があります。

デフォルトでは、カード支払いとその他の一般的な支払い方法が有効になっています。企業と顧客に適した追加の支払い方法を有効にできます。プロダクトと決済手段のサポートについては、Stripe の決済手段のサポートを、手数料については料金体系ページをご覧ください。

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

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

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

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

前

後

const stripe =
    Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const elements = stripe.elements();

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
};
const elements = stripe.elements(options);

オプション支払い中に支払いの詳細を保存する

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

一部の支払い方法は、決済時に保存できません。これらの支払い方法も他のユースケース用に有効にできますが、将来の決済に備えた設定時にオプションとして顧客に表示されることはありません。

const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  setup_future_usage: 'off_session',
};
const elements = stripe.elements(options);

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

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

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

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

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

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

前

後

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

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

前

後

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

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

オプションApple Pay マーチャントトークン (MPAN) をリクエストする

Express Checkout Element は Apple Pay トークンをサポートとしているため、デバイストークンではなく、Apple Pay マーチャントトークンを使用して、継続支払い、後払い、自動リロード支払いなど加盟店が開始する取引 (MIT) を有効化することをお勧めします。マーチャントトークン (MPAN) は自社と顧客の Apple ウォレット支払い方法を接続するので、MPAN は複数のデバイスで機能し、支払い情報が紛失または盗難されたデバイスから削除された場合でも、新しいデバイスで有効な状態が維持されます。実装について、詳細は 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 のスタイルを設定する

支払い方法のボタン (Google Pay や Apple Pay など) は、個別にスタイルを設定して、さまざまなテーマとタイプを指定できます。

Appearance API の borderRadius 変数も使用できます。

前

後

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

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

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

confirm イベントをリッスンして、確定を処理します。決済情報を収集して Stripe に送信するには、stripe.confirmCardPayment などの個別の確定メソッドではなく、stripe.confirmPayment を使用します。

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

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

カード支払いの決済フローで、必要な場合にのみリダイレクトを行うようにする場合、redirect に if_required を設定できます。これは、Express Checkout Element には適用されません。

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

前

後

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

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

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

支払いが完了すると、Stripe は payment_intent.succeeded イベントを送信します。ダッシュボードの Webhook ツールを使用するか Webhook のガイドに従ってこれらのイベントを受信し、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行します。

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

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

イベント	説明	アクション
payment_intent.succeeded	顧客が正常に支払いを完了したときに送信されます。	顧客に注文の確定を送信し、顧客の注文のフルフィルメントを実行します。
payment_intent.processing	顧客が正常に支払いを開始したが、支払いがまだ完了していない場合に送信されます。このイベントは、多くの場合、顧客が口座引き落としを開始するときに送信されます。その後、`payment_intent.succeeded` イベント、また、失敗の場合は `payment_intent.payment_failed` イベントが送信されます。	顧客に注文確認メールを送信し、支払いが保留中であることを示します。デジタル商品では、支払いの完了を待たずに注文のフルフィルメントを行うことが必要になる場合があります。
payment_intent.payment_failed	顧客が支払いを試みたが、支払いに失敗する場合に送信されます。	支払いが `processing` から `payment_failed` に変わった場合は、顧客に再度支払いを試すように促します。