> ## Documentation Index
> Fetch the complete documentation index at: https://waffo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# タイムアウトと結果が最終確定するタイミング

> タイムアウトした注文が決済失敗の証明にならない理由：クローズ時刻に Waffo が行うこと、タイムアウトをどちらの時計が決めるか、どの失敗が通知として届き、どれが照会でのみ判明するか、遅れて届く通知と再送、遅延成功後の自動返却、独立した 3DS 認証タイムアウト、そしてフロントエンドがどれだけ待つべきか。

[決済結果の確認](/docs/ja/support/payment-results-faq)は、本ページが依拠するルールを確立しています：\*\*リダイレクトは決して決済の証明ではなく、権威ある結果は Webhook であり、Order Inquiry がそのフォールバックです。\*\*本ページはこのルールの後半、すなわち結果を*いつ*最終確定として扱ってよいのか、そしてタイムアウトがなぜその瞬間に含まれないのかを扱います。

> \*\*覚えておくべき一文：\*\*タイムアウトした注文は、Waffo が待つのをやめたことを意味します。決済手段が止まったことも、ユーザーがもう支払えないことも意味しません。

## 注文がタイムアウトしました。決済は確実に行われないのですか？

いいえ。タイムアウトは Waffo が貴社の注文について下した判断であり、決済手段がその決済について下した判断ではありません。

いくつかの決済手段では、貴社の注文がクローズされた後も、決済は決済手段側で非最終状態のままです。そちら側には自動クローズがまったく存在しません。この状況では：

* ユーザーは依然として決済ページやアプリを開き、決済を完了できます。
* 注文がタイムアウトと表示された**後**に決済が成功することがあります。
* 結果通知がクローズ後に届くことがあります。

したがって、タイムアウトした注文は*暫定的な*失敗です。購入記録を破棄せず、予約済みの座席やライセンスを不可逆的に解放せず、ユーザーに「決済は失敗し、お金は引き落とされません」と伝えないでください。試行が完了しなかったこと、そして再度支払う前に確認すべきことを伝えてください。

## 注文がクローズ時刻に達したとき、Waffo は実際に何をしますか？

決済がどこまで進んだかによって、2 つの異なる処理が行われます：

| 注文がどこまで進んだか | クローズ時刻に起こること |
| - | - |
| ユーザーが決済を一度も送信していない — 注文が決済試行に到達していない | Waffo が注文をクローズし、タイムアウトを貴社に報告します |
| 注文にすでに決済試行が存在する | 定期クローズはそれを**スキップ**します — 注文は失敗に強制されるのではなく、実際の結果に基づいて確定するよう残されます |

決済手段がサポートしている場合、Waffo はその時点で決済手段にも決済のクローズを依頼します。サポートしていない場合、決済は決済手段側の独自ルールで期限切れになるまで、そちら側で単に開いたままになります。

これが `TIMEOUT_CLOSE` と `TIMEOUT_CHANNEL_CLOSE` の意味が異なる理由です。その区別については
[決済結果の確認](/docs/ja/support/payment-results-faq)をご覧ください。また、上表の 2 行目が加盟店の想定以上に重要である理由でもあります：承認が始まった*後*に停止した注文は、タイマーによって強制的に失敗にされることはありません。

## 決済が遅れたかどうかは、どちらの時計が決めますか — 私のものか、決済手段のものか？

決済手段のものです。`orderExpiredAt` で設定する有効期限は、ユーザーがチェックアウトページで注文を送信できる時間枠を規定します。決済が決済手段に引き渡された後は、**その決済手段自身のサーバー時刻が**決済が時間内に到着したかどうかを**決定します**。

実務上の影響：

* 決済手段側のネットワーク遅延や再試行により、決済が貴社の時間枠を超えても、決済手段側の時計では時間内とされることがあります。
* 貴社の締め切りの直前または直後に決済手段に到達した決済は、依然として通常どおり処理されることがあります。
* 貴社のクローズ時刻と決済手段のクローズ時刻は 2 つの異なる時計であり、同期していません。

貴社自身の有効期限は、UI と後処理上の締め切りとして扱い、資金上の締め切りとしては扱わないでください。

## 決済が失敗したとき、またはユーザーがまったく支払わなかったとき、通知は届きますか？

**注文**がクローズされたときは届きます。しかし、個々の**試行**が失敗したときに必ず届くわけではなく、この 2 つの間のギャップが「何も届かなかった」というチケットの最も一般的な原因です。

| 結果 | 通知 |
| - | - |
| 決済成功 | `PAYMENT_NOTIFICATION`、`orderStatus` = `PAY_SUCCESS` |
| 注文がクローズされる — タイムアウト、キャンセル、または決済手段が最終的な失敗を報告したため | `PAYMENT_NOTIFICATION`、`orderStatus` = `ORDER_CLOSE`、理由は `orderFailedReason` に含まれます。これは Waffo 自身が送信するもので、決済手段には依存しません |
| 試行が失敗したが注文は開いたまま | \*\*まだ何も届きません。\*\*いくつかの決済手段では、失敗した試行は注文をクローズしません — ユーザーはその中で再試行できます — そのため、注文自体が最終状態に達するまで通知は生成されません |
| ユーザーが単に支払わない | 注文の有効期限でクローズされるまで何も届きません。その後、上記の `ORDER_CLOSE` 通知が届きます |

つまり、貴社が待っているかもしれない通知は失われたのではなく、注文が終わるのを待っているのです。それまでは、状態を確認する唯一の方法は照会です：
`/api/v1/order/inquiry`。ポーリングは最初の照合ギャップが発生した後ではなく、本番稼働前に構築してください。クローズ通知に含まれる内容については
[各ステータスで注文に対して何ができますか？](/docs/ja/support/order-status-actions-and-capture-faq)
をご覧ください。

実用的なパターン：注文が開いている間は 30 秒ごとに、上限回数までポーリングし、その後、遅延成功を捕捉するために貴社自身のクローズ時刻の後にもう一度ポーリングします。最終状態を得たらすぐにポーリングを停止してください。

## すでに注文をクローズした後に通知が届きました。これはバグですか？

いいえ、いくつかの決済手段では想定された挙動です。決済手段の通知メカニズムは、貴社の注文が期限切れになったからといって止まりません。決済が成功していれば通知は送信され、確認応答がなければ**再送**されます。複数回になることもあります。

したがって、貴社のハンドラーは、貴社が終了済みと考えている注文に対する成功通知を受け入れなければなりません。具体的には：

1. 貴社側で注文がクローズされているからといって通知を拒否しないでください。受け入れ、確認応答し、事後に照合してください。
2. ハンドラーを冪等にしてください — 再送は同じイベントが複数回届くことを意味します。[Webhook の再送](/docs/ja/developer-docs/webhook/retry)をご覧ください。
3. `Content-Type: application/json` とボディ
   `{"message":"success"}` で確認応答してください。そうしないと再送スケジュールが継続して発火します。
4. 遅延成功に対して貴社のビジネスがどうするかを一度だけ決めてください：履行するか、返金するか。どちらも正当ですが、ルールがないことは正当ではありません。

## ユーザーがタイムアウト後に支払いました。お金は自動的に返却されますか？

場合によります。一部のカードスキームのウォレット型決済手段では、決済手段自身の決済タイムアウト後に到着した決済は**自動的に返却**されます — 決済手段自身が返却を開始し、貴社も Waffo も何もしなくても金額はカード保有者に戻ります。返却は即時ではなく、決済手段自身のスケジュールでカード保有者の口座に着金します。これは決済手段自身の挙動であり、Waffo のサービスレベルではありません。

その他のほとんどの決済手段では、自動返却は**ありません**。遅延成功は本物の成功です：資金は移動しており、注文は支払済みであり、履行したくない場合は返金しなければなりません。
[決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq)をご覧ください。

両方の結果が存在するため、ユーザーに「自動的に返金されます」と伝えないでください。まず注文を確認してください。

## フロントエンドはエラーを表示するまでどれだけ待つべきですか？

明示的な上限を設定してください。リダイレクトして戻るフローの妥当なデフォルトは**最大 5 分**で、待機中は数秒ごとに注文ステータスをポーリングします。その後：

* 待機を止め、中立的なメッセージを表示します：決済を確認できなかったため、ユーザーは再試行すべきである、と。
* \*\*再試行のために新しい注文を作成します。\*\*元の注文を再利用しないでください。
* 旧注文に対するサーバー側のポーリングは継続してください — ユーザーのブラウザが諦めたことは、決済について何も語りません。

やってはいけないこと：待機ページで無限にスピナーを回すこと、または待機時間が切れた瞬間に「決済失敗」と表示すること。前者はユーザーを失い、後者は重複決済を生みます。

## 3DS 認証がタイムアウトしました。同じ注文で再試行できますか？

いいえ。3DS 認証には**注文の有効期限とは独立した、独自の有効期限**があります — 認証リンクは生成された瞬間から短い固定期間のみ有効で、一般的な注文の有効期限よりかなり短いものです。ユーザーがその時間枠内に認証を完了しなかった場合、注文はその理由で失敗状態になり、**再利用できません**。

正しい復旧方法は**新しい注文を作成する**ことです。ユーザーを古い認証リンクに戻したり、元の注文を再送信しても機能しません：

| 状況 | 対応 |
| - | - |
| ユーザーが 3DS ページを離脱し、後で戻ってきた | 新しい注文を作成 |
| 認証リンクが期限切れ | 新しい注文を作成 |
| 認証は完了したが結果がまだない | 待機 / ポーリング — これはタイムアウトではありません |

なお、フリクションレス 3DS 認証でも、ユーザーが非常に素早く通過するリダイレクトが発生します。そのリダイレクトを見ただけでは結果にはなりません — 他のあらゆる場所と同じルールが適用されます。

## ある照会では決済失敗と返り、後の照会では成功と返りました。どちらが正しいのですか？

後の方です。いくつかの決済手段では、失敗した試行は注文をクローズ**しません** — ユーザーは同じ注文内で自由に再試行でき、後続の試行が成功することがあります。2 回の試行の間に実行された照会は、失敗した方を正確に報告しています。

時刻付きのシーケンス例：

| 時刻 | 起こったこと | 照会が返すもの |
| - | - | - |
| 1:00 | ユーザーの最初の試行が失敗 | — |
| 1:03 | 貴社が照会 | 失敗 |
| 1:05 | ユーザーが再試行し成功 | — |
| 1:06 | 貴社が照会 | 成功 |

ここから導かれるルール：\*\*失敗は、注文自体が最終確定したときにのみ最終確定します。\*\*注文がまだ開いている間は、失敗結果を「この注文は決して支払われない」ではなく「この試行はうまくいかなかった」として扱ってください。具体的には：

* 最初の失敗で在庫を解放したり購入をキャンセルしないでください。
* 注文が開いている間は、失敗でポーリングを止めないでください。
* ユーザーに再試行の経路を示してください — これらの決済手段では、既存の注文内で再試行することこそが想定された挙動です。

*本当に*最終確定である失敗とは、クローズされた注文ステータスを伴うもの、または注文作成時に拒否されたものです。

## 実際に何が最終確定とみなされますか？

| シグナル | 最終確定？ |
| - | - |
| 最終的な注文ステータスを報告する Webhook 決済結果 | **はい** |
| 最終的な注文ステータスを返す `/api/v1/order/inquiry` | **はい** |
| 貴社サイトへのリダイレクト | いいえ |
| 貴社自身のタイムアウトの経過 | いいえ |
| `E`xxxxx「ステータス不明」レスポンス | いいえ — 照会を続けてください |
| ユーザーのスクリーンショットや申告 | いいえ |

最初の 2 行のみが、履行、会計処理、返金の判断を駆動できます。それ以外はすべてヒントにすぎません。

## タイムアウトに対して安全な連携とはどのようなものですか？

実装を照らし合わせるためのチェックリスト：

1. `orderExpiredAt` は意図的に UTC+0 で設定されており、それがチェックアウトページの時間枠のみを規定することを理解している。
2. すべての注文に、ユーザーがブラウザを閉じても継続するサーバー側ポーリングがある。
3. Webhook ハンドラーは、すでにクローズした注文の通知を受け入れ、確認応答し、照合する。
4. ハンドラーは同じイベントの重複配信に対して冪等である。
5. 再試行は**新しい**注文を作成する。期限切れの注文を再利用するものは何もない。
6. 遅延成功に対する書面のルール — 履行または返金 — がある。
7. コードのどこも、経過時間、リダイレクト、`E` コードを最終結果として扱わない。

## 次にどこを見ればよいですか？

| 質問 | ページ |
| - | - |
| 各 `orderStatus` の意味、`webUrl` と `successRedirectUrl` の違い、Webhook の欠落 | [決済結果の確認](/docs/ja/support/payment-results-faq) |
| 数日間開いたままになる銀行振込・バーチャル口座の注文 | [銀行振込とバーチャル口座](/docs/ja/support/bank-transfer-and-virtual-account-faq) |
| 遅延成功の返金 | [決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq) |
| 注文作成時に見られるエラーコード | [エラーコードと上限の補足](/docs/ja/support/error-codes-and-limits-supplement) |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.