Sources API 使用のベストプラクティス非推奨

Sources API は高い柔軟性を備えているので、新しい支払い方法を導入する際、その方法に対応するために必要な変更を最小限に抑えることができます。

カード支払いの一般的なフロー

カード支払い (3D セキュアを除く) の一般的な決済フローでは、実装がカード情報を収集してソースを作成し、それを支払いリクエストの実行に使用します。顧客による追加操作は不要であり、カード支払いは同期確認を提供しているため、支払いが成功したかどうか、売上が保証されているかどうかをすぐに確認できます。Webhook を使用する必要はありません。

Webhook の使用が必要な状況

他の支払い方法の場合は、ソースが chargeable になり支払いリクエストの実行に使用できるようになる前に、顧客による追加の対応 (リダイレクトなど) が必要になることがあります (iDEAL など)。この移行は通常は非同期的に発生し、顧客がお客様の Web サイトを離れた後で発生することもあります。これらの理由により、実装で Webhook を使用して、支払いの作成前にソースが請求可能になるタイミングを特定する必要があります。

Stripe は次の Webhook イベントを送信し、ソースのステータスの変化を通知します。

同様に、支払いを作成する際、一部の非同期型の支払い方法では、売上が確定され支払いが完了するまで数日かかることがあります。この場合、注文を確定し、最終的にフルフィルメントを実行するタイミングを把握するために Webhook が必要です。

支払いのステータスの変化について通知するため、次の Webhook イベントが送信されます。

柔軟な組み込みの構築

決済プロセスが柔軟であり、複数の支払い方法に対応できるようにするために、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(
'pk_test_TYooMQauvdEDq54NiTphI7jx');

// 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();

以下の表は、ソースのステータスに基づいて表示可能な、顧客に表示される推奨メッセージの例を示します。

支払いの作成後 (かつユーザーがまだ確認ページにいる場合)、支払いのステータスに基づいて以下のメッセージを表示できます。

注文の確定

必ず 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 をリッスンして、受信した支払いに関連付けられた注文をキャンセルする必要もあります。

これらの各イベントについて、顧客に注文が失敗したことを通知し、必要に応じて顧客が支払いフローに戻れるようにすることをお勧めします。