Payment Intents Quickstart ／ Payment Intents クイックスタート

docs

Payments > PREPARING FOR SCA ＞ Payment Intents > Quickstart
・PaymentIntents Quickstart
・PaymentIntentsクイックスタート
・PaymentIntentsでの支払いを受け取る方法を学ぶ
・ElementsとPayment Intents APIを使用して1回限りの支払いを行い、カード決済を受け入れる方法を学ぶ

支払いの完了方法に応じて

「Payment Intents API」を使用してカードの支払いを受け取る方法が2つある
・自動確認と手動確認だ

自動確認フロー
・クライアントでの支払いを確認し、支払いが成功したときにWebフックを使用して通知する

手動確認フロー
・サーバーでの支払いが確認され、支払いが成功した直後にサーバーで支払いを実行できる

自動確認のクイックスタート

自動確認
・Payment Intents API を使用するための最も早い方法だ
・カードの3Dセキュア認証など、一部の支払い方法には非同期フローがあるため、自動確認システムでは、支払い後ロジックを処理するためにWebフックを使用する必要がある

処理の流れ

場所	処理内容
Server	-
↓	-
Client	confirm
↓	-
Webhooks	fulfill

PaymentIntentsとStripe Elementsを使用したカード支払いの受け入れ
※サーバーサイドとクライアントサイドのアクションを伴う5段階のプロセスである
・1.サーバーで PaymentIntent を作成する
・2.PaymentIntent のクライアントシークレットをクライアントへ渡す(クライアントサイドで PaymentIntent のクライアントシークレットを利用可能にする)
・3.(「Stripe Elements」を設定後、)クライアントで支払い方法の詳細を収集する
・4.クライアントからStripeへ支払いを送信する
・5.顧客の注文を非同期的に処理する

ステップ1：サーバーで PaymentIntent を作成する

PaymentIntent
・顧客から支払いを集めるというあなたの意図を表し、各段階を通して支払いプロセスのライフサイクルを追跡するオブジェクトである
・PaymentIntentを作成するときに、通貨、許可されたソースタイプ、および顧客から集金したい金額収集したい金額と通貨を指定する
・次の例は、サーバーにPaymentIntentを作成する方法を示している

PaymentIntentデモ1-0
・payment_method_typesパラメータを未指定
・デフォルトは[“ card”]

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



$intent = \Stripe\PaymentIntent::create([

  'amount' => 1099,

  'currency' => 'jpy',

]);

PaymentIntentデモ1-1
・payment_method_typesパラメータを明示的に指定

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



\Stripe\PaymentIntent::create([

  "amount" => 1099,

  "currency" => "eur",

  "payment_method_types" => ["card"],

]);

顧客がチェックアウトプロセスを開始したときなど、金額が判明したらすぐにPaymentIntentを作成することをお勧めする
・カート小計の更新時や配送料と税金の計算時など、金額が変更された場合は、金額を更新できる
・顧客から集金する金額がチェックアウトプロセス中に変更された場合（例えば、カート内の小計が変更された場合、または配送料と税金が計算された場合）、それに応じてPaymentIntentオブジェクトを更新する

次の例は、PaymentIntentの金額を更新する方法を示している
・第1引数で 'pi_xxxx'として指定している内容は、PaymentIntentオブジェクトのid
・存在しないidを指定すると、「Fatal error: Uncaught Stripe\Error\InvalidRequest: No such payment_intent」エラーが発生する
・PaymentIntentデモ1-2

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



\Stripe\PaymentIntent::update(

  'pi_xxxx',

  [

    'amount' => 1499,

  ]

);

ステップ2：PaymentIntentのクライアントシークレットをクライアント側へ渡す

クライアントサイドでPaymentIntentのクライアントシークレットを利用可能にする
・PaymentIntentオブジェクトには、 クライアントシークレット(client_secretプロパティ) 、つまり「請求を作成するためにクライアント側のStripe.jsへ渡す必要がある一意のキー」が含まれている
・アプリケーションでサーバーサイドレンダリングを使用している場合は、テンプレートフレームワークを使用して、 データ属性または hidden のHTML要素を使用してクライアントシークレットをページに埋め込む

PaymentIntentデモ2

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



//$intent = # ... Fetch or create the PaymentIntent;

$intent1 = \Stripe\PaymentIntent::create([

  'amount' => 1099,

  'currency' => 'jpy',

]);



$intent2 = \Stripe\PaymentIntent::update(

  $intent1['id'],

  [

    'amount' => 1499,

  ]

);

?>



<input id="cardholder-name" type="text">

<!-- placeholder for Elements -->

<div id="card-element"></div>

<button id="card-button" data-secret="<?php echo $intent2->client_secret; ?>">

  Submit Payment

</button>

各PaymentIntentは通常、アプリケーション内の単一の「カート」または顧客セッションと相関している
・チェックアウト時にPaymentIntentを作成し、そのIDをアプリケーションのデータモデルのユーザーのカートに保存して、必要に応じて再度取得することができる

クライアントシークレットを使用して、PaymentIntentに指定された金額で支払い処理を完了することができる
・ログに記録したり、URLに埋め込んだり、顧客以外に公開したりしないでくれ
・クライアントシークレットを含むページでTLSが有効になっていることを確認してくれ

ステップ3：(「Stripe Elements」を設定後、)クライアントで支払い方法の詳細を収集する

PaymentIntentsはStripe.jsと完全に統合されている
・Elementsを使用してクライアント側で安全に支払い情報を収集し、それをStripeへ送信して料金を作成する
・Elementsを使い始めるには、あなたのウェブサイトに次のスクリプトタグを含める

<script src="https://js.stripe.com/v3/"></script>

PCIに準拠するためには
・このスクリプトを常にjs.stripe.comから直接ロードする必要がある
・バンドルに含めたり、自分でコピーをホストすることはできない

Stripeの高度な詐欺機能を最大限に活用するには
・チェックアウトページだけでなく、サイトのすべてのページにこのスクリプトを含める
・すべてのページにスクリプトを含めることで、StripeはユーザーがWebサイトを閲覧したときに詐欺を示す可能性がある異常な動作を検出することができる

Stripeオブジェクトのインスタンス
・次に、最初のパラメータとして publishable APIキーを指定して、 Stripeオブジェクトのインスタンスを作成する
・PaymentIntentsのStripe.js機能にアクセスするためのオプションとして、以下に示すbetas値も必ず指定してくれ
・Elementsオブジェクトのインスタンスを作成し、それを使用してCard要素をページ内の適切なプレースホルダにマウントする

・正式版のコード

const stripe = Stripe('pk_test_xxxx');



const elements = stripe.elements();

const cardElement = elements.create('card');

cardElement.mount('#card-element');

・payment_intent_beta_3バージョンの頃のコード

const stripe = Stripe('pk_test_××××', {

  betas: ['payment_intent_beta_3']

});



const elements = stripe.elements();

const cardElement = elements.create('card');

cardElement.mount('#card-element');

ステップ4： クライアントからStripeへ支払いを送信する

支払いを完了するには
・2番目のステップで利用可能になったクライアントシークレットを取得する
・data属性からクライアントシークレットを取得したら、 stripe.handleCardPaymentを使って支払いを完了する

・正式版のコード

const cardholderName = document.getElementById('cardholder-name');

const cardButton = document.getElementById('card-button');

const clientSecret = cardButton.dataset.secret;



cardButton.addEventListener('click', async (ev) => {

  const {paymentIntent, error} = await stripe.handleCardPayment(

    clientSecret, cardElement, {

      payment_method_data: {

        billing_details: {name: cardholderName.value}

      }

    }

  );



  if (error) {

    // Display error.message in your UI.

    console.log(error);

  } else {

    // The payment has succeeded. Display a success message.

    console.log("成功");

  }

});

・payment_intent_beta_3バージョンの頃のコード

const cardholderName = document.getElementById('cardholder-name');

const cardButton = document.getElementById('card-button');

const clientSecret = cardButton.dataset.secret;



cardButton.addEventListener('click', async (ev) => {

  const {paymentIntent, error} = await stripe.handleCardPayment(

    clientSecret, cardElement, {

      source_data: {

        owner: {name: cardholderName.value}

      }

    }

  );



  if (error) {

    // Display error.message in your UI.

    console.log(error);

  } else {

    // The payment has succeeded. Display a success message.

    console.log("成功");

  }

});

システムがSCA対応であることを確認するには
・顧客の名前、Eメール、請求先住所、および配送先住所（ある場合）を stripe.handleCardPayment 呼び出しに必ず提供してくれ

認証など、支払いを完了するために顧客が追加の手順を実行する必要がある場合
・Stripe.jsはその手順を実行する
・支払いが正常に完了すると、返されたPaymentIntentのstatusプロパティの値はsucceededである
・支払いが成功しなかった場合は、返されたerrorを調べて原因を特定できる

ステップ5： 顧客の注文を非同期的に処理する

//中略

支払いが成功したときに通知を受けて履行を促進するには、非同期イベントを処理する必要がある

注文を処理する方法はいくつかある
・ウェブフックを設定する
//中略

PaymentIntentが顧客から支払いを回収しようとすると、chargeオブジェクトが作成される
・PaymentIntentの charges プロパティを調べて、試行されたchargeの完全なリストを取得できる
※retrieveメソッドの第1引数で 'pi_xxxx'として指定している内容は、PaymentIntentオブジェクトのid
・課金は時系列の逆順にリストされているため、最新の料金が配列の先頭になる
・この配列には、最後の成功した課金金額に加えて、支払い処理中に発生した失敗した課金額も含まれている

PaymentIntentデモ5

// Set your secret key: remember to change this to your live secret key in production

// See your keys here: https://dashboard.stripe.com/account/apikeys

\Stripe\Stripe::setApiKey("sk_test_xxxx");



$intent = \Stripe\PaymentIntent::retrieve("pi_xxxx");

$charges = $intent->charges->data;

・Stripe.jsから返されたPaymentIntentを使用して、顧客の支払いが成功または失敗したときに直ちに顧客にフィードバックを提供できる
・ただし、支払いを受け取った時点でフルフィルメントを推進する場合は、一貫性を維持するために、サーバー上でpayment_intent.succeededイベントとpayment_intent.payment_failedイベントを監視することをお勧めする

手動確認のクイックスタート

・省略

システムをテストする

テストすることが重要
・「追加の認証を必要とするカード」と「ユーザーにとって最もスムーズなチェックアウトエクスペリエンスを保証しないカード」を正しく処理していることを確認するために、Payment Intents API システムを徹底的にテストすることが重要だ
・さまざまな種類のカードをシミュレートするためにテストモードで使用できるテストカードがある

システムを検証するために使用する必要がある2枚のテストカード
・3Dセキュア必須および3Dセキュア不要のカード
・これらのカード番号は、「将来の有効期限」と「3桁のCVCコード」(を入力すること)で使用できる

一覧表

カード番号	3Dセキュアな使い方	説明
4000000000003220	必須	このテストカードはすべてのトランザクションで3D Secure 2を必要とし、テストモードで3D Secure 2をトリガーする
4000000000003055	サポートしているが必須ではない	このテストカードは3D Secure 2をサポートしているが必須ではなく、テストモードで追加の認証手順を必要とする

・アプリケーションまたは支払いデモで、これらのカードを使用して、さまざまな動作を確認してくれ

ビューポートメタタグの要件

すべてのデバイスで優れたユーザーエクスペリエンスを提供するには
・ページのビューポートwidthをdevice-widthに設定する必要がある
・これはviewportメタタグで行われる
・他にもいくつかのビューポート設定があり、必要に応じて設定できる
・設定のどこかにwidth=device-widthを含めるようにしてくれ

・例えば、次のものはElementsで動作する

・あなたのページにすでにこのタグがあり、それにwidth=device-width含まれていれば、すべて設定済みだ

width=device-widthを設定せずにElementsを使用しても機能するが
・とにかく追加することを強くお勧めする
・以下省略