Sources API 使用のベストプラクティス非推奨
警告
Stripe は Sources API を廃止しており、現地の決済手段のサポートを今後無効にする予定です。Sources API を使用して現地の決済手段のいずれかを処理している場合は、Payment Methods API に移行する必要があります。このサポート終了に関する詳細については、メール通知をお送りします。
Stripe はカード決済のサポートを終了する予定はありませんが、Sources API のご利用を PaymentMethods API に切り替えることをお勧めします。PaymentMethods API を使用することで、最新機能と決済手段のタイプを利用できます。
Sources API は高い柔軟性を備えているので、新しい支払い方法を導入する際、その方法に対応するために必要な変更を最小限に抑えることができます。
カード支払いの一般的なフロー
カード支払い (3D セキュアを除く) の一般的な決済フローでは、組み込みがカード情報を収集してソースを作成し、それを支払いリクエストの実行に使用します。顧客による追加操作は不要であり、カード支払いは同期確認を提供しているため、支払いが成功したかどうか、売上が保証されているかどうかをすぐに確認できます。Webhook を使用する必要はありません。
Webhook の使用が必要な状況
他の支払い方法の場合は、ソースが chargeable
になり支払いリクエストの実行に使用できるようになる前に、顧客による追加の対応 (リダイレクトなど) が必要になることがあります (iDEAL など)。この移行は通常は非同期的に発生し、顧客がお客様の Web サイトを離れた後で発生することもあります。これらの理由により、組み込みで Webhook を使用して、支払いの作成前にソースが請求可能になるタイミングを特定する必要があります。
Stripe は次の Webhook イベントを送信し、ソースのステータスの変化を通知します。
イベント | 説明 | 推奨されるアクション |
---|---|---|
source.chargeable | 顧客が支払いを認証し、確認すると、 Source オブジェクトが chargeable になります。 | 支払いを作成します。 |
source.failed | 顧客が支払いの認証を拒否したため、Source オブジェクトが請求可能になりませんでした。 | 注文をキャンセルし、(オプションとして) 顧客を再び支払いフローに戻します。 |
source.canceled | Source オブジェクトの期限が切れたため、支払いの作成には使用できません。 | 注文をキャンセルし、(オプションとして) 顧客を再び支払いフローに戻します。 |
同様に、支払いを作成する際、一部の非同期型の決済手段では、売上が確定され支払いが完了するまで数日かかることがあります。この場合も、注文を確定し、最終的にフルフィルメントを実行するタイミングを把握するために Webhook が必要です。
支払いのステータスの変化について通知するため、次の Webhook イベントが送信されます。
イベント | 説明 | 推奨されるアクション |
---|---|---|
charge.pending | Charge は保留中です (非同期型の支払いのみ)。 | 必要な対応はありません。 |
charge.succeeded | Charge が成功し、支払いが完了しました。 | 注文を確定して、顧客に確認のメールを送信します。 |
charge.failed | Charge が失敗し、支払いを完了できませんでした。 | 注文をキャンセルし、(オプションとして) 顧客を再び支払いフローに戻します。 |
柔軟な組み込みの構築
決済プロセスが柔軟であり、複数の支払い方法に対応できるようにするために、Stripe は次のアプローチを推奨しています。
ソースの作成
Source (ソース) の作成時に、注文の内部表記のソース ID を記録して、source.chargeable
Webhook を受信および処理する際にその注文を取得できるようにします。効率的に検索を行うため、必ずこの source
属性に基づいて Order オブジェクトにインデックスを付けてください。
支払いの作成
source.chargeable
Webhook の配信によって、ソースに対する請求が行われます。Webhook を受信したら、受け取ったソース ID で検索して注文の内部表記を取得し、注文が支払いを待っていることを確認します。
支払いリクエストを作成する際、内部的な注文 ID をべき等キーとして使用して、競合状態を未然に防ぎます。さらに、ソースが再利用可能で、再利用を希望する場合は、請求前にソースを Customer (顧客) に関連付けてください。1 回限りの使用および再利用可能なソースの処理方法と、ソースが顧客とどのように連携するかの詳細については、1 回限りの使用または再利用可能およびソースと顧客のガイドを参照してください。
ソースの作成時と同様に、注文の内部表記の支払い ID を記録して、charge.succeeded
Webhook を受信および処理する際にその注文を取得できるようにします。
確認ページ
顧客が支払いの承認に必要な操作 (リダイレクトに従うなど) を行った後で、注文の状態を示した確認ページを提示する必要があります。内部的に注文をポーリングすることにより、これを実行できます。
Webhook の配信待ち時間は保証されないため、確認ページをさらに合理化するには、クライアント側のコードで関連する Source のステータスをポーリングします。Source が chargeable
になったことを検出したら、source.chargeable
Webhook の到着を待たずに、Source を使用した Charge の作成を開始できます。
ソースの種類によっては、chargeable
になるまで数分 (あるいは数日) かかることに注意してください。ソースをポーリングする場合は、ある時点でタイムアウトして、注文が支払いの確定を待っていることを顧客に伝え、次に支払い確定メールを非同期で送信することをお勧めします。以下の表に、ソースのステータスごとに顧客に表示する Stripe の推奨メッセージを示しています。
顧客がページを離れると、クライアント側のポーリングは停止します。このため、顧客の注文を継続して追跡できるように、source.chargeable
Webhook に備えた組み込みを行う必要があります。
Stripe.js を使用している場合は、stripe.retrieveSource() を使用して独自のポーリングを実装できます。
// In order-confirmation-page.js const stripe = Stripe(
); // After some amount of time, we should stop trying to resolve the order synchronously: const MAX_POLL_COUNT = 10; let pollCount = 0; const pollForSourceStatus = async () => { const {source} = await stripe.retrieveSource({id: SOURCE_ID, client_secret: CLIENT_SECRET}) if (source.status === 'chargeable') { // Make a request to your server to charge the Source. // Depending on the Charge status, show your customer the relevant message. } else if (source.status === 'pending' && pollCount < MAX_POLL_COUNT) { // Try again in a second, if the Source is still `pending`: pollCount += 1; setTimeout(pollForSourceStatus, 1000); } else { // Depending on the Source status, show your customer the relevant message. } }; pollForSourceStatus();'pk_test_TYooMQauvdEDq54NiTphI7jx'
以下の表は、ソースのステータスに基づいて表示可能な、顧客に表示される推奨メッセージの例を示します。
ステータス | 顧客に表示されるメッセージ |
---|---|
ソースは chargeable | 注文を受領し、支払いの確定を待っています。 |
ソースは canceled | 支払いは失敗し、注文を処理できませんでした。 |
ソースは failed | 支払いは失敗し、注文を処理できませんでした。 |
ソースはポーリング後しばらくしても pending のまま | 注文を受領し、支払いの確定を待っています。 |
支払いの作成後 (かつユーザーがまだ確認ページにいる場合)、支払いのステータスに基づいて以下のメッセージを表示できます。
ステータス | 顧客に表示されるメッセージ |
---|---|
支払いは pending | 注文を受領し、支払いの確定を待っています。 |
支払いは failed | 支払いは失敗し、注文を処理できませんでした。 |
支払いは succeeded | 支払いは確定され、注文が完了しました。 |
注文の確定
必ず charge.succeeded
Webhook を受信した後で注文を確定してください (これはすぐに送信される場合と、そうではない場合があります) 。非同期型の支払いでは支払いの確定に数日かかる場合があるため、この段階で顧客にメールを送信します。
キャンセルと失敗
source.canceled
および source.failed
Webhook をリッスンして、対象のソースに関連付けられた注文をキャンセルしてください。上記のベストプラクティスに従っている場合、以前に chargeable
だったソースに対する source.canceled
Webhook を受信することはありません (source.chargeable
ハンドラは、支払いを即時作成して、ソースがキャンセルされるのを防ぎます)。ただし一度も chargeable
にならず、pending
のままのソースに対する source.canceled
Webhook は受信します。これは、ほとんどの場合、顧客が決済フローを早い段階で離れたことを示します。顧客が支払いを拒否したか、決済スキーマのレベルで技術的な問題が発生した場合には、source.failed
Webhook を受信することもあります。
また、charge.failed
Webhook をリッスンして、受信した支払いに関連付けられた注文をキャンセルする必要もあります。
これらの各イベントについて、顧客に注文が失敗したことを通知し、必要に応じて顧客が支払いフローに戻れるようにすることをお勧めします。