**覚えておくべき一文：**タイムアウトした注文は、Waffo が待つのをやめたことを意味します。決済手段が止まったことも、ユーザーがもう支払えないことも意味しません。
注文がタイムアウトしました。決済は確実に行われないのですか？
いいえ。タイムアウトは Waffo が貴社の注文について下した判断であり、決済手段がその決済について下した判断ではありません。 いくつかの決済手段では、貴社の注文がクローズされた後も、決済は決済手段側で非最終状態のままです。そちら側には自動クローズがまったく存在しません。この状況では：- ユーザーは依然として決済ページやアプリを開き、決済を完了できます。
- 注文がタイムアウトと表示された後に決済が成功することがあります。
- 結果通知がクローズ後に届くことがあります。
注文がクローズ時刻に達したとき、Waffo は実際に何をしますか？
決済がどこまで進んだかによって、2 つの異なる処理が行われます：
決済手段がサポートしている場合、Waffo はその時点で決済手段にも決済のクローズを依頼します。サポートしていない場合、決済は決済手段側の独自ルールで期限切れになるまで、そちら側で単に開いたままになります。
これが
TIMEOUT_CLOSE と TIMEOUT_CHANNEL_CLOSE の意味が異なる理由です。その区別については
決済結果の確認をご覧ください。また、上表の 2 行目が加盟店の想定以上に重要である理由でもあります：承認が始まった後に停止した注文は、タイマーによって強制的に失敗にされることはありません。
決済が遅れたかどうかは、どちらの時計が決めますか — 私のものか、決済手段のものか？
決済手段のものです。orderExpiredAt で設定する有効期限は、ユーザーがチェックアウトページで注文を送信できる時間枠を規定します。決済が決済手段に引き渡された後は、その決済手段自身のサーバー時刻が決済が時間内に到着したかどうかを決定します。
実務上の影響：
- 決済手段側のネットワーク遅延や再試行により、決済が貴社の時間枠を超えても、決済手段側の時計では時間内とされることがあります。
- 貴社の締め切りの直前または直後に決済手段に到達した決済は、依然として通常どおり処理されることがあります。
- 貴社のクローズ時刻と決済手段のクローズ時刻は 2 つの異なる時計であり、同期していません。
決済が失敗したとき、またはユーザーがまったく支払わなかったとき、通知は届きますか？
注文がクローズされたときは届きます。しかし、個々の試行が失敗したときに必ず届くわけではなく、この 2 つの間のギャップが「何も届かなかった」というチケットの最も一般的な原因です。
つまり、貴社が待っているかもしれない通知は失われたのではなく、注文が終わるのを待っているのです。それまでは、状態を確認する唯一の方法は照会です：
/api/v1/order/inquiry。ポーリングは最初の照合ギャップが発生した後ではなく、本番稼働前に構築してください。クローズ通知に含まれる内容については
各ステータスで注文に対して何ができますか？
をご覧ください。
実用的なパターン：注文が開いている間は 30 秒ごとに、上限回数までポーリングし、その後、遅延成功を捕捉するために貴社自身のクローズ時刻の後にもう一度ポーリングします。最終状態を得たらすぐにポーリングを停止してください。
すでに注文をクローズした後に通知が届きました。これはバグですか？
いいえ、いくつかの決済手段では想定された挙動です。決済手段の通知メカニズムは、貴社の注文が期限切れになったからといって止まりません。決済が成功していれば通知は送信され、確認応答がなければ再送されます。複数回になることもあります。 したがって、貴社のハンドラーは、貴社が終了済みと考えている注文に対する成功通知を受け入れなければなりません。具体的には：- 貴社側で注文がクローズされているからといって通知を拒否しないでください。受け入れ、確認応答し、事後に照合してください。
- ハンドラーを冪等にしてください — 再送は同じイベントが複数回届くことを意味します。Webhook の再送をご覧ください。
Content-Type: application/jsonとボディ{"message":"success"}で確認応答してください。そうしないと再送スケジュールが継続して発火します。- 遅延成功に対して貴社のビジネスがどうするかを一度だけ決めてください：履行するか、返金するか。どちらも正当ですが、ルールがないことは正当ではありません。
ユーザーがタイムアウト後に支払いました。お金は自動的に返却されますか？
場合によります。一部のカードスキームのウォレット型決済手段では、決済手段自身の決済タイムアウト後に到着した決済は自動的に返却されます — 決済手段自身が返却を開始し、貴社も Waffo も何もしなくても金額はカード保有者に戻ります。返却は即時ではなく、決済手段自身のスケジュールでカード保有者の口座に着金します。これは決済手段自身の挙動であり、Waffo のサービスレベルではありません。 その他のほとんどの決済手段では、自動返却はありません。遅延成功は本物の成功です：資金は移動しており、注文は支払済みであり、履行したくない場合は返金しなければなりません。 決済手段別の返金制限をご覧ください。 両方の結果が存在するため、ユーザーに「自動的に返金されます」と伝えないでください。まず注文を確認してください。フロントエンドはエラーを表示するまでどれだけ待つべきですか？
明示的な上限を設定してください。リダイレクトして戻るフローの妥当なデフォルトは最大 5 分で、待機中は数秒ごとに注文ステータスをポーリングします。その後：- 待機を止め、中立的なメッセージを表示します：決済を確認できなかったため、ユーザーは再試行すべきである、と。
- **再試行のために新しい注文を作成します。**元の注文を再利用しないでください。
- 旧注文に対するサーバー側のポーリングは継続してください — ユーザーのブラウザが諦めたことは、決済について何も語りません。
3DS 認証がタイムアウトしました。同じ注文で再試行できますか？
いいえ。3DS 認証には注文の有効期限とは独立した、独自の有効期限があります — 認証リンクは生成された瞬間から短い固定期間のみ有効で、一般的な注文の有効期限よりかなり短いものです。ユーザーがその時間枠内に認証を完了しなかった場合、注文はその理由で失敗状態になり、再利用できません。 正しい復旧方法は新しい注文を作成することです。ユーザーを古い認証リンクに戻したり、元の注文を再送信しても機能しません：
なお、フリクションレス 3DS 認証でも、ユーザーが非常に素早く通過するリダイレクトが発生します。そのリダイレクトを見ただけでは結果にはなりません — 他のあらゆる場所と同じルールが適用されます。
ある照会では決済失敗と返り、後の照会では成功と返りました。どちらが正しいのですか？
後の方です。いくつかの決済手段では、失敗した試行は注文をクローズしません — ユーザーは同じ注文内で自由に再試行でき、後続の試行が成功することがあります。2 回の試行の間に実行された照会は、失敗した方を正確に報告しています。 時刻付きのシーケンス例：
ここから導かれるルール：**失敗は、注文自体が最終確定したときにのみ最終確定します。**注文がまだ開いている間は、失敗結果を「この注文は決して支払われない」ではなく「この試行はうまくいかなかった」として扱ってください。具体的には：
- 最初の失敗で在庫を解放したり購入をキャンセルしないでください。
- 注文が開いている間は、失敗でポーリングを止めないでください。
- ユーザーに再試行の経路を示してください — これらの決済手段では、既存の注文内で再試行することこそが想定された挙動です。
実際に何が最終確定とみなされますか？
最初の 2 行のみが、履行、会計処理、返金の判断を駆動できます。それ以外はすべてヒントにすぎません。
タイムアウトに対して安全な連携とはどのようなものですか？
実装を照らし合わせるためのチェックリスト：orderExpiredAtは意図的に UTC+0 で設定されており、それがチェックアウトページの時間枠のみを規定することを理解している。- すべての注文に、ユーザーがブラウザを閉じても継続するサーバー側ポーリングがある。
- Webhook ハンドラーは、すでにクローズした注文の通知を受け入れ、確認応答し、照合する。
- ハンドラーは同じイベントの重複配信に対して冪等である。
- 再試行は新しい注文を作成する。期限切れの注文を再利用するものは何もない。
- 遅延成功に対する書面のルール — 履行または返金 — がある。
- コードのどこも、経過時間、リダイレクト、
Eコードを最終結果として扱わない。