Payment Intents API への移行

Stripe Billing、Stripe Tax や割引、配送、通貨換算の使用をご希望の場合

サブスクリプション、税金、割引、配送、通貨換算を管理する Payment Element のシステムを開発しています。詳細については、決済ページを構築するガイドをご覧ください。

既存のカードと Charges API 組み込みを移行する方法は以下のとおりです。

決済フローの移行は非常に煩雑な場合があります。Payment Intents API を段階的に採用し、それを Charges API と並行して使用するのが安全です。この目的のために、移行を次のステップに分割できます。

API バージョンとクライアントライブラリを更新します。
該当する場合は、支払いプロパティから読み取るコードを移行して、Charges API によって作成された支払いと Payment Intents API によって作成された支払いの間の読み取りパスの整合性を確保します。これにより、読み取り側のシステムが支払いの古いシステムと新しいシステムの両方で機能するようになります。
Web、iOS、および Android の既存の Charges API の実装を、Payment Intents API を使用するように移行します。
Customer オブジェクトにカードを保存する組み込みを移行します。
規制用テストカードでテストして、アップグレードしたシステムが認証を正しく処理することを確認します。

API バージョンとクライアントライブラリを更新する

Payment Intents API はすべての API バージョンで機能しますが、最新の API バージョンにアップグレードすることをお勧めします。2019-02-11 より古い API バージョンを使用する場合は、コード例を確認しながら、以下の 2 つの変更点に注意します。

requires_source は requires_payment_method に名前が変更されています
requires_source_action は requires_action に名前が変更されています

さらに、Stripe の SDK のいずれかを使用している場合、Payment Intents API を使用するには、最新バージョンのライブラリにアップグレードする必要があります。

1 回限りの支払いフローを移行

Stripe.js および Elements を使用して構築された組み込みは、以下のステップで構成されます。

サーバ側で支払いを回収する Intent を登録する
クライアント側で支払いの詳細を収集する
支払いの作成を開始する
サーバ側で顧客の注文のフルフィルメントを実行する

ステップ 1: サーバ側で支払いを回収する Intent を登録する

サーバーで PaymentIntent を作成し、クライアント側でアクセスできるようにします。

前

後

以前は未対応

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="usd"

ステップ 2: クライアント側で支払いの詳細を収集する

confirmCardPayment 関数を使用して、支払い情報を収集し、Stripe に直接送信します。

前

後

stripe.createToken(
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  INTENT_SECRET_FROM_STEP_1,
  {
    payment_method: {card: cardElement}
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

ステップ 3: 支払いの作成を開始する

既存の組み込みでは、最後のステップでトークン化された支払い情報を使用してサーバで支払いを作成していますが、このステップは不要になりました。これは、前のステップで呼び出される confirmCardPayment 関数が支払いの作成を開始するためです。

前

後

Command Line
curl https://api.stripe.com/v1/charges \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

前のステップで完了

ステップ 4: 顧客の注文のフルフィルメントを実行

自動確認では、クライアント側での顧客のアクションに基づいて非同期で支払いが作成されるため、Webhook を監視して支払いが正常に完了するタイミングを判断する必要があります。顧客の支払いが成功した後に注文のフルフィルメントなどのステップを実行するには、Webhook のサポートを実装して、payment_intent.succeeded イベントを監視します。

前

後

支払いが成功した場合は、フルフィルメントを実行します。

payment_intent.succeeded Webhook に登録し、Webhook ハンドラでフルフィルメントを実行します。

移行が完了できました。次のセクションではテストカードを使用して、アップグレードした組み込みが 3D セキュア認証を処理することを確認します。

Customer オブジェクトにカードを保存する組み込みに移行する

決済フローでカード情報を収集する Payment Intents API 組み込みは、次のステップで構成されます。

サーバ側で支払いを回収する Intent を登録する
クライアント側で支払いの詳細を収集する
支払いの作成を開始する
サーバ側で顧客の注文のフルフィルメントを実行する

ステップ 1: サーバ側で支払いを回収する Intent を登録する

サーバーに PaymentIntent を作成します。ユーザーがアプリケーションの外部にいるときに主にユーザーに請求する予定の場合は、setup_future_usage を off_session に設定し、アプリケーションでユーザに請求する予定の場合は on_session に設定します。オンセッションとオフセッションの両方の支払いにカードを使用する場合は、off_session を使用します。Customer ID とともに setup_future_usage パラメーターを指定すると、PaymentIntent が確定され、顧客による必要な操作が完了した後、結果の PaymentMethod がその Customer に保存されます。次に、PaymentIntent にクライアント側でアクセスできるようにします。

前

後

以前は未対応

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "setup_future_usage"="off_session" \
  -d "amount"=1099 \
  -d "currency"="usd"

ステップ 2: クライアント側で支払いの詳細を収集する

confirmCardPayment 関数を使用して、支払い情報を収集し、Stripe に直接送信します。

前

後

stripe.createToken(
// or stripe.createSource
  cardElement
).then(function(token) {
  // Send token to server
});

stripe.confirmCardPayment(
  '{{INTENT_SECRET_FROM_STEP_1}}',
  {
    payment_method: {card: cardElement},
  }
).then(function(result) {
  if (result.error) {
    // Display error.message in your UI.
  } else {
    // The payment has succeeded
    // Display a success message
  }
});

最後に、支払い方法 (paymentIntent.payment_method) を顧客に関連付けます。

前

後

Command Line
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}}/sources \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{TOKEN_OR_SOURCE}}"

Command Line
curl https://api.stripe.com/v1/payment_method/{{PAYMENT_METHOD_ID}}/attach \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "customer"="{{CUSTOMER_ID}}"

ステップ 3: 支払いの作成を開始する

前

後

Command Line
curl https://api.stripe.com/v1/charges \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "source"="{{FROM_PREVIOUS_STEP}}" \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "amount"=1099 \
  -d "currency"="usd"

前のステップで完了

ステップ 4: 顧客の注文のフルフィルメントを実行

前

後

支払いが成功した場合は、フルフィルメントを実行します。

payment_intent.succeeded Webhook に登録し、Webhook ハンドラでフルフィルメントを実行します。

保存された支払い方法にアクセスする

以前に保存した顧客のカード、ソース、PaymentMethods を表示するには、Customer オブジェクトの sources プロパティを読み取る代わりに、支払い方法をリストアップします。顧客に追加された新しい PaymentMethod は Customer オブジェクトの sources プロパティに複製されないため、このようにする必要があります。

前

後

Command Line

customer.sources

Command Line
curl https://api.stripe.com/v1/payment_methods?customer={{CUSTOMER_ID}}&type=card \
  -usk_test_4eC39HqLyjWDarjtT1zdp7dc
:

組み込みをテストする

実装内容を十分にテストして、追加の認証が必要なカードと不要なカードが正しく処理されることを確認します。将来の日付の有効期限と 3 桁のセキュリティコードとともに、これらのカード番号をテスト環境で使用し、認証が必要な場合と不要な場合について、システムを検証します。

番号	認証	説明
	設定時または最初の取引時に必要	このテストカードは、1 回限りの支払いの認証が必要です。ただし、Setup Intents API を使用してこのカードを設定し、それ以降の支払いに保存したカードを使用する場合は、追加の認証の必要はありません。
	必須	このテストカードは、すべての取引で認証を必要とします。
	必須	このテストカードには認証が必要ですが、認証の成功後に、支払いは `insufficient_funds` エラーコードで拒否されます。
	対応可能	このテストカードは、3D セキュア 2 による認証に対応していますが、必須ではありません。テスト環境の Radar ルールによって認証が要求されない限り、このカードを使用する支払いには、テスト環境での追加認証は必要ありません。

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

Payment Intents API への移行

Stripe Billing、Stripe Tax や割引、配送、通貨換算の使用をご希望の場合

API バージョンとクライアントライブラリを更新する

1 回限りの支払いフローを移行

ステップ 1: サーバ側で支払いを回収する Intent を登録する

ステップ 2: クライアント側で支払いの詳細を収集する

ステップ 3: 支払いの作成を開始する

ステップ 4: 顧客の注文のフルフィルメントを実行

Customer オブジェクトにカードを保存する組み込みに移行する

ステップ 1: サーバ側で支払いを回収する Intent を登録する

ステップ 2: クライアント側で支払いの詳細を収集する

ステップ 3: 支払いの作成を開始する

ステップ 4: 顧客の注文のフルフィルメントを実行

保存された支払い方法にアクセスする

組み込みをテストする

参照情報