# Source から Klarna を移行する システムを Sources API から Payment Intents API に移行します。 Klarna では、[Payment Methods API](https://docs.stripe.com/api/payment_methods.md) と [Payment Intents API](https://docs.stripe.com/api/payment_intents.md) を使用する新しい決済プロセスが開始されます。このガイドでは、*Stripe Checkout* (A low-code payment integration that creates a customizable form for collecting payments. You can embed Checkout directly in your website, redirect customers to a Stripe-hosted payment page, or create a customized checkout page with Stripe Elements) を使用したローコードオプションなど、[Sources API](https://docs.stripe.com/api/sources.md) による移行の推奨手段について概説します。 > #### 非推奨の機能 > > Stripe では Klarna での Sources API の使用を非推奨にしました。2024 年早期に完全に削除する予定です。現在も Sources API を使用して Klarna による支払いを処理している場合は、今すぐ PaymentMethods および PaymentIntents を使用するように移行してください。 ![PaymentIntents での Klarna 取引フローの開始](https://b.stripecdn.com/docs-statics-srv/assets/klarna_on_pi_image_1.506e683101b89d2a5c34b5d5d7bde362.png) PaymentIntents で Klarna の支払いを開始する ![PaymentIntents での Klarna 取引フローの完了](https://b.stripecdn.com/docs-statics-srv/assets/klarna_on_pi_image_2.8ab6e30014bbbf5e9afd33268bddea0b.png) PaymentIntents で Klarna の支払いを完了する ## 重要な相違点 - **Klarna 製品の選択**: 構築済みの Stripe システムで Klarna 製品の種類を指定する必要はありません。代わりに、顧客が Klarna のリダイレクトページで製品を選択します。決済サイトに、対応可能な Klarna 支払いオプションごとに個別のボタンを追加しないでください。Klarna ボタンを 1 つだけ追加してください。 - **Klarna SDK のインライン表示はサポート対象外**: 顧客は、支払いを承認するために、支払いページから Klarna サイトにリダイレクトしなければならなくなりました。このため、Klarna SDK を読み込んだり、インラインコンポーネントをレンダリングする必要はありません。 - **支払いの確認はすべての市場で同期的に行われる**: これまでは、支払いが成功したかどうかの確認は、非同期で行われることがありました。顧客の承認後、直ちに支払いが成功したかどうかを検出できるようになりました。 > 現在 Stripe の実装にプラグインを使用している場合、プラグイン開発者が PaymentMethods および PaymentIntents を使用するようにそのプラグインを移行する必要があります。Stripe またはプラグインの設定に変更を加える必要があるかどうかについては、プラグイン開発者にお問い合わせください。 ## 決済フローを移行する Klarna の導入をウェブ決済に移行するには、[PaymentIntents API](https://docs.stripe.com/api/payment_intents.md) を使用できるようにサーバーとフロントエンドを更新する必要があります。典型的な実装オプションは次の 3 つです。 - 決済フローの [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) にリダイレクトする。 - 自社の決済ページで Stripe の [Payment Element](https://docs.stripe.com/payments/payment-element.md) を使用する。 - 自社のフォームを作成し、Stripe JS SDK を使用して支払いを完了する。 [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) または [Payment Element](https://docs.stripe.com/payments/payment-element.md) を使用すると、コードを変更せずに Stripe ダッシュボードからほとんどの決済方法を追加したり管理したりできます。 以下は、以前の実装ステップと新しい実装ステップを大まかに比較したものです。 | 以前の実装 | Stripe Checkout | Payment Element | 自社のフォーム | | ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | | 複雑度: 低 | 複雑度: 中 | 複雑度: 高 | | フロントエンドまたはサーバー上に Source を作成する | サーバー上に Checkout セッションを作成する | サーバで PaymentIntent を作成する | サーバで PaymentIntent を作成する | | Klarna SDK を使用して Klarna ウィジェットを読み込み、支払いを承認する OR Klarna にリダイレクトして、支払いを承認する | 不要 | client secret をフロントエンドに渡し、Stripe JS SDK を使用して Payment Element をレンダリングし、支払いを完了する | client secret をフロントエンドに渡す。自社のフォームを使用して顧客から追加情報を収集し、Stripe JS SDK を使用して Klarna にリダイレクトする | | Source が請求可能であることを確認し、請求する | 不要 | 不要 | 不要 | | `charge.succeeded` Webhook を使用して支払いが成功したことを非同期で確認する | Checkout セッションが成功したことを `payment_intent.succeeded` Webhook で確認する | PaymentIntent が成功したことを `payment_intent.succeeded` Webhook で確認する | PaymentIntent が成功したことを `payment_intent.succeeded` Webhook で確認する | > PaymentIntent は、新しい実装で支払いを表すオブジェクトで、フロントエンドで支払いを確認すると Charge を作成します。これまでデータベースに Charge への参照を保存していた場合は、顧客が支払いを完了した後に PaymentIntent から Charge ID を取得することで、引き続き保存できます。ただし、PaymentIntent ID も保存しておくことをお勧めします。 ## オプション 1： Checkout セッションを使用する [Stripe Checkout](https://docs.stripe.com/payments/checkout.md) は、ローコードでホストされた決済ソリューションで、Klarna 決済だけでなく、Stripe がサポートするさまざまな支払い方法を受け付けることができます。現在、自社サイトで決済ページをホストしていて、それに代えて Stripe Checkout を使用する場合は、次を実行してください。 1. Klarna が[ダッシュボードで有効](https://Dashboard.stripe.com/settings/payment_methods)になっていることを確認します。 1. [サーバーで Checkout セッションを作成](https://docs.stripe.com/payments/klarna/accept-a-payment.md?payment-ui=checkout)します。`klarna` を `payment_method_types` の 1 つとして明示的に設定することも、[動的な決済手段](https://docs.stripe.com/payments/dashboard-payment-methods.md)を使用することもできます。 1. 物品を販売する場合は、[配送先住所の収集を有効にする](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-shipping_address_collection)か、[`shipping_details` ハッシュ](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-shipping_details)に配送先住所を含めます。 1. 購入者の支払い準備ができたら、セッション URL にリダイレクトします。 ## オプション 2： Payment Element を使用する [Stripe Payment Element](https://docs.stripe.com/payments/payment-element.md) は、Klarna やその他の支払い方法をサポートする、支払いページ用の単一の埋め込み UI コンポーネントです。これは Stripe Checkout の機能を数多く提供しますが、自社の支払いページに表示できます。Payment Element を使用するには、次を実行してください。 1. Klarna が[ダッシュボードで有効](https://Dashboard.stripe.com/settings/payment_methods)になっていることを確認します。 1. お使いのサーバーで PaymentIntent を作成します。 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "automatic_payment_methods[enabled]"=true \ -d amount=1099 \ -d currency=eur ``` Klarna を [payment_method_types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) の 1 つとして設定して明示的に有効にすることができます。 1. PaymentIntent Client Secret をフロントエンドに渡して、[Stripe Elements UIライブラリを初期化](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements#collect-payment-details)します。 1. [Payment Element を作成](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#add-the-payment-element-to-your-payment-page)してそのページに埋め込みます。このエレメントは、顧客が選択した決済手段で必須となる追加フィールドの入力内容を自動で収集します。 1. ユーザーが支払いを送信したときに [Payment Element でconfirmPayment を呼び出します](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#web-submit-payment)。`return_url` を必ず渡してください。 ## オプション 3： カスタムフォームを作成する You can build your own form components and complete a Klarna payment by using the Stripe JS SDK. Read more about the [full integration](https://docs.stripe.com/payments/klarna/accept-a-payment.md?payment-ui=direct-api). To integrate in this method, do the following: 1. [ダッシュボードで Klarna を有効化している](https://dashboard.stripe.com/settings/payment_methods)ことを確認します。 1. お使いのサーバーで [PaymentIntent を作成](https://docs.stripe.com/payments/klarna/accept-a-payment.md?payment-ui=direct-api#create-payment-intent)します。 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "automatic_payment_methods[enabled]"=true \ -d amount=1099 \ -d currency=eur ``` ダッシュボードで決済手段を管理しない場合は、Klarna を [payment_method_types](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types) の 1 つとして設定することで明示的に有効にできます。 1. フォームを使用して、顧客のメールアドレスと請求先の国を収集します。 1. 顧客が決済を承認する準備ができたら、PaymentIntent の Client Secret を指定し、[決済画面で Stripe.JS を初期化し、`confirmKlarnaPayment` を呼び出します](https://docs.stripe.com/payments/klarna/accept-a-payment.md?payment-ui=direct-api#submit-payment)。`billing_details[email]` と `billing_details[address][country]` フィールドにメールアドレスと請求先の国が存在することを確認してください。 ## フィールドマッピングリファレンス Payment Element または自社のフォームを使用する場合は、以前に Source にあったフィールドを PaymentIntent にマッピングしなおす必要があります。以下の表は、以前のフィールドと新しいフィールドのマッピングです。物品を販売する場合は、配送先情報を渡すことをお勧めします。その他のフィールドはすべて任意で、Klarna がそのページで必要な追加情報を収集します。 | 以前の Source フィールド | 新しい PaymentIntent フィールド | 注 | | ---------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **必須フィールド** | | `type` | `payment_method_types[]` | これは PaymentIntents の配列です。支払い方法のリストを手動で作成する場合は、配列の要素の 1 つとして `klarna` を設定します。 | | `amount` | `amount` | | | `currency` | `currency` | | | `owner[email]` | `payment_method_data[billing_details][email]` | Payment Element を使用する場合は必須ではありません。自動的に収集されます。 | | `owner[address][country]` | `payment_method_data[billing_details][address][country]` | Payment Element を使用する場合は必須ではありません。自動的に収集されます。 | | **物品を販売する場合に推奨** | | `klarna[shipping_first_name]` | `shipping[name]` | 姓と名の両方を、空白で区切られた単一の文字列として入力します。 | | `klarna[shipping_last_name]` | `shipping[name]` | 姓と名の両方を、空白で区切られた単一の文字列として入力します。 | | `order[shipping][address]` | `shipping[address]` | コンポーネントについては、[API リファレンス](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-shipping-address)をご覧ください。 | | `order[shipping][carrier]` | `shipping[carrier]` | | | `order[shipping][tracking_number]` | `shipping[tracking_number]` | | | `order[shipping][phone]` | `shipping[phone]` | | | **その他のオプションフィールド** | | `klarna[purchase_country]` | `payment_method_data[billing_details][address][country]` | | | `klarna[first_name]` | `payment_method_data[billing_details][name]` | 任意。姓と名の両方を、空白で区切られた単一の文字列として入力します。 | | `klarna[last_name]` | `payment_method_data[billing_details][name]` | 任意。姓と名の両方を、空白で区切られた単一の文字列として入力します。 | | **不要になりました** | | `klarna[product]` | | PaymentIntents には適用されません。顧客は Klarna のサイトで支払いを承認する際に Klarna の製品を選択します。 | | `klarna[shipping_delay]` | | 適用されません。出荷の遅延が予想される場合は、[オーソリとキャプチャーの分離](https://docs.stripe.com/payments/klarna/accept-a-payment.md?platform=web&ui=direct-api#manual-capture)を使用して、商品が出荷された後にのみ支払いをキャプチャーします。 | | `source_orders[items]` | | 不要になりました。 | > 現在、Source で [`klarna[attachment]` パラメーター](https://docs.stripe.com/payments/klarna/accept-a-payment.md) または `order[items]` パラメーターを使用している場合は、これらのパラメーターに関する詳細を Stripe からご連絡いたします。 ## 購入後 支払いが完了した後、ご利用の実装ポイントに対して次の変更が必要です。 ### 支払いステータスの確認 以前は、実装で API コールのたびに Source と Charge の両方のステータスを確認する必要がありましたが、2 つのステータスをチェックする必要はもうありません。フロントエンドでの確定後に、PaymentIntent または Checkout セッションのステータスを確認するだけで済みます。 | payment_intent.status | 意味 | 注 | | ------------------------- | -------------------------------- | ------------------------------------------------------------------------------------- | | `succeeded` | 支払いが成功しました。 | | | `requires_payment_method` | 支払いが失敗しました。 | | | `requires_action` | 顧客は Klarna のサイトで支払いの承認を完了していません。 | 顧客が 48 時間以内に決済を完了しない場合、PaymentIntent は requires_payment_method に移行し、確定を再試行できるようになります。 | PaymentIntent のステータスは、必ずサーバーで取得するか、サーバーで Webhook をリッスンして確認してください。PaymentIntent を確定する際に指定される `return_url` にユーザーが戻ることだけに依存しないでください。[決済後イベント](https://docs.stripe.com/payments/klarna/accept-a-payment.md?payment-ui=direct-api#fulfillment)の処理について詳細を確認してください。 ### 返金 PaymentIntent が作成した Charge を使用して、引き続き Refunds API を呼び出すことができます。Charge の ID は `latest_charge` パラメーターで確認できます。または、Refunds API に Charge の代わりに PaymentIntent ID を指定することもできます。 ## エラー処理 これまでは、Source が作成されたときにエラーを処理する必要がありました。PaymentIntents では、Source でエラーを確認する必要はなく、代わりにPaymentIntent の作成時と顧客が支払いを承認した後に PaymentIntent のエラーを確認する必要があります。PaymentIntent のエラーのほとんどは、無効なリクエストで返された[タイプフィールド](https://docs.stripe.com/api/errors.md#errors-type)に関するものです。 | Source 作成時の以前のエラーコード | PaymentIntent の作成または確認時の新しいエラータイプ | 注 | | ------------------------------ | --------------------------------- | ------------------------------------------------ | | `payment_method_not_available` | `invalid_request_error` | | | `processing_error` | `invalid_request_error` | | | `missing_sku_item_quantity` | | 適用されません。PaymentIntent の作成時に、販売アイテムを指定する必要はありません。 | | `country_currency_mismatch` | `invalid_request_error` | | | `country_not_supported` | `invalid_request_error` | | | `invalid_currency` | `invalid_request_error` | | | `invalid_email` | `invalid_request_error` | | | `invalid_phone` | | 適用されません。このフィールドは必須ではなく、Klarna のページで収集されます。 | | `invalid_address` | | 適用されません。このフィールドは必須ではなく、Klarna のページで収集されます。 | ## Webhook これまで Source イベントをリッスンしていた場合は、新しいイベントタイプをリッスンするように実装の更新が必要になる場合があります。 以下は、リッスンする新しいイベントタイプのリファレンスです。 | 以前の Webhook | Checkout の新しい Webhook | PaymentIntent の新しい Webhook | 注 | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------- | | `source.chargeable` | 適用外 | 適用外 | | | `source.failed` | 適用外 | 適用外 | | | `source.canceled` | 適用外 | 適用外 | | | `charge.succeeded` | `checkout.session.completed` | `payment_intent.succeeded` | `charge.succeeded` Webhook も送信されるため、新しい Webhook をリッスンするように実装を更新する必要はありません。 | | `charge.failed` | 適用されません。 顧客は[有効期限が切れる](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-expires_at)まで同じ Checkout セッションで支払いを再試行でき、有効期限が切れた時点で `checkout.session.expired` イベントが届きます。 | `payment_intent.payment_failed` | `charge.failed` Webhook も送信されるため、新しい Webhook をリッスンするように実装を更新する必要はありません。 | | `charge.dispute.created` | `charge.dispute.created` | `charge.dispute.created` | |