Payment Intents API と Payment Methods API に移行する
The Payment Methods API replaces the existing Tokens and Sources APIs as the recommended way for integrations to collect and store payment information. It works with the Payment Intents API to create payments for a wide range of payment methods.
Stripe は、Sources API での現地の決済手段のサポートを終了する予定です。現在 Sources API を使用して現地の決済手段を処理している場合は、Payment Methods API に移行する必要があります。このサポート終了に関する詳細については、メール通知をお送りします。
While we don’t plan to turn off support for card payment methods, we still recommend that you migrate them to the Payment Methods and Payment Intents APIs. For more information about migrating card payment methods, see Migrating to the Payment Intents API.
現地の決済手段を Sources API から Payment Intents API に移行する
To migrate your integration for local payment methods, update your server and front end to use the PaymentIntents API. There are three typical integration options:
- Redirect to Stripe Checkout for your payment flow.
- Use the Stripe Payment Element on your own payment page.
- 自社のフォームを作成し、Stripe JS SDK を使用して支払いを完了する。
Stripe Checkout または Payment Element を使用する場合、コードを変更せずに Stripe ダッシュボードからほとんどの決済手段を追加したり管理したりできます。
For specific information about integrating a local payment method using the Payment Methods API, see the instructions for that payment method in the payment methods documentation. The following table provides a high-level comparison of the different payment types.
以前の実装 | Stripe Checkout | Payment Element | 自社のフォーム |
---|---|---|---|
複雑度: 低 | 複雑度: 中 | 複雑度: 高 | |
フロントエンドまたはサーバーで Source を作成する | サーバーで Checkout セッションを作成する | サーバーで PaymentIntent を作成する | サーバーで PaymentIntent を作成する |
ウィジェットを読み込むか、サードパーティーにリダイレクトして支払いを承認する | 不要 | client secret をフロントエンドに渡し、Stripe JS SDK を使用して Payment Element をレンダリングし、支払いを完了する | client secret をフロントエンドに渡し、自社のフォームを使用して顧客から追加情報を収集し、決済手段に応じて支払いを完了する |
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 も保存しておくことをお勧めします。
フィールドのマッピング
Payment Element または自社のフォームを使用する場合は、Source フィールドを PaymentIntent フィールドに再度マッピングする必要があります。固有のフィールドは、決済手段によって異なります。
支払いステータスの確認
以前は、実装で API コールのたびに Source と Charge の両方のステータスを確認する必要がありましたが、今後は 2 つのステータスをチェックする必要はありません。フロントエンドでの確定後に、PaymentIntent または Checkout セッションのステータスを確認するだけで済みます。
payment_intent.status | 意味 | 注 |
---|---|---|
succeeded | 支払いが成功しました。 | |
requires_payment_method | 支払いが失敗しました。 | |
requires_action | 顧客は支払いの承認を完了していません。 | 顧客が 48 時間以内に支払いを完了しない場合、PaymentIntent は requires_payment_method に移行し、確定を再試行できるようになります。 |
PaymentIntent のステータスは、必ずサーバーで取得するか、サーバーで Webhook をリッスンして確認してください。PaymentIntent を確定する際に指定される return_url
にユーザーが戻ることのみで判断しないようにしてください。
返金
PaymentIntent が作成した Charge を使用して、引き続き Refunds API を呼び出すことができます。Charge の ID は latest_charge
パラメーターで確認できます。
または、Refunds API に Charge の代わりに PaymentIntent ID を指定することもできます。
エラー処理
これまでは、Source でエラーを処理する必要がありました。PaymentIntents を使用する場合、Source でエラーを確認する代わりに、PaymentIntent の作成時と顧客が支払いを承認した後に PaymentIntent のエラーを確認する必要があります。PaymentIntent のエラーのほとんどは、無効なリクエストで返された invalid_request_error
タイプによるものです。
実装を移行する際は、PaymentIntent のエラーコードが Sources の対応するエラーコードと一致しない場合があることにご注意ください。
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 | Not applicable - The customer can re-attempt the payment on the same Checkout Session until it expires, at which point you receive a checkout.session.expired event. | payment_intent.payment_failed | charge.failed Webhook も送信されるため、新しい Webhook をリッスンするように、構築済みのシステムを更新する必要はありません。 |
charge.dispute.created | charge.dispute.created | charge.dispute.created |
Payment Methods API に移行する
The main difference between the Payment Methods and Sources APIs is that Sources describes transaction state through the status property. That means that each Source
object must transition to a chargeable state before it can be used for a payment. In contrast, a PaymentMethod
is stateless, relying on the PaymentIntent object to represent payment state.
注
以下の表には、すべての決済手段が掲載されているわけではありません。Sources API を使用してこの他の決済手段を導入している場合は、それらも同様に Payment Methods API に移行してください。
フロー | Integrate Payment Method with Payment Intents API | Charges API を使用した Tokens と Sources |
---|---|---|
カード | Card payments | Supported on Tokens; Not recommended on Sources |
ACH ダイレクトデビット | US bank account direct debits | Supported on Tokens Not supported on Sources |
Alipay | Alipay payments | Deprecated |
Bancontact | Bancontact payments | Deprecated |
EPS | EPS payments | Deprecated |
giropay | giropay payments | Deprecated |
iDEAL | iDEAL payments | Deprecated |
Klarna | Klarna payments | Deprecated |
Multibanco | Planned | Deprecated Beta |
Przelewy24 | Przelewy24 payments | Deprecated |
SEPA ダイレクトデビット | Single Euro Payments Area direct debits | Deprecated |
Sofort | Sofort payments | Deprecated |
WeChat Pay | WeChat Pay payments | Deprecated |
導入する API を選択したら、決済手段ガイドを参考にして、顧客に対してサポート対象にする適切な決済手段タイプを決定できます。
このガイドには各決済手段の詳細が記載され、顧客対応フローの違いと、その決済手段に最も適した地域について説明されています。利用可能な決済手段は、ダッシュボードで有効にすることができます。通常は即時に有効化され、追加の契約や時間のかかるプロセスは必要ありません。
Compatibility with legacy reusable payment methods
If you previously processed any of the following reusable payment methods using Sources, the existing saved sources don’t migrate automatically. To preserve your existing customers’ saved payment methods, you must convert those sources to payment methods using a data migration tool in the Stripe Dashboard. For instructions on how to convert them, see the support page.
- Alipay
- Bacs ダイレクトデビット
- SEPA ダイレクトデビット
レガシーのカードオブジェクトとの互換性
If you previously collected card customer payment details with Stripe using cards or Sources, you can start using the Payment Methods API immediately without migrating any payment information.
Customer に保存された互換性のある支払い手段は、PaymentMethod オブジェクトを受け付けるすべての API で使用できます。たとえば、PaymentIntent を作成するときは、保存したカードを PaymentMethod として使用できます。
オブジェクトを PaymentIntent に関連付けるときは、互換性のある支払い手段の保存先である顧客 ID を忘れずに指定してください。
You can retrieve all saved compatible payment instruments through the Payment Methods API.
この互換性があるために、新しいオブジェクトが作成されないことに注意してください。Payment Methods API は、基となるオブジェクトが同じでありながら、提供されるビューが異なります。たとえば、Payment Methods API で互換性のある支払い手段を更新した場合、その更新は Sources API でも表示され、また、その逆も同様です。