> ## 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.

# 決済結果の確認

> 決済が成功したかどうかを確実に判定する方法：リダイレクト、webUrl、Webhook、Order Inquiry それぞれの役割、各 orderStatus の意味、通知が届かないときの対処。

このページの質問は、実際の加盟店とのやり取りから直接取り上げたものです。
最も重要なルールは 1 つです：

> \*\*リダイレクトは、ユーザーのブラウザがお客様のサイトに戻ってきたことを意味するだけです。
> 決済の証明には決してなりません。\*\*決済結果の正式な情報源は
> [Webhook 通知](/docs/ja/developer-docs/webhook/overview)であり、照合用のフォールバックとして
> Order Inquiry API があります。

## ユーザーが自社サイトにリダイレクトされて戻ってきました——決済は成功していますか？

必ずしもそうではありません。`successRedirectUrl` は UI 上の遷移にすぎません。次のいずれかで
結果を確認してください（推奨順）：

1. **Webhook** — 決済が完了または失敗した時点で、Waffo が `notifyUrl` に決済結果を送信します。
2. **Order Inquiry** — 照合が必要なときは `/api/v1/order/inquiry` を呼び出して注文を能動的に
   照会します。

いずれかが最終的な成功を報告したときにのみ、注文を支払済みとしてください。

## リダイレクトされる前にユーザーがブラウザを閉じました——決済は失敗したのですか？

いいえ。決済は決済手段側でそのまま完了する可能性があります。Webhook はユーザーのブラウザの
動作に関係なく発火します。疑わしい場合は Order Inquiry を呼び出してください。

## `webUrl` と `successRedirectUrl` の違いは何ですか？

両者は逆方向に進みます：

| フィールド | 方向 | 意味 |
| - | - | - |
| `webUrl`（`orderAction` 内） | ユーザーを決済**へ**送る | `orderStatus` が `AUTHORIZATION_REQUIRED` で `actionType` が `WEB` の場合、ユーザーを `webUrl` にリダイレクトして認可／支払いを行わせます。`DEEPLINK` の場合は代わりに `deeplinkUrl` を使います。 |
| `successRedirectUrl`（注文作成パラメータ） | 決済後にユーザーが**戻って**くる | 決済成功後にユーザーが到達する場所。省略可——省略した場合、ユーザーは Waffo のチェックアウト画面に留まります。 |

`failedRedirectUrl` と `cancelRedirectUrl` は、同じ仕組みで失敗時とユーザーキャンセル時の
戻り先を扱います。

## 各 `orderStatus` の値はどういう意味ですか？

| ステータス | 意味 |
| - | - |
| `PAY_IN_PROGRESS` | 注文は受け付けられ、ユーザーが支払い中です。 |
| `AUTHORIZATION_REQUIRED` | 決済手段がユーザーの認可を必要としています——`orderAction` で示されたページにユーザーを誘導してください。 |
| `AUTHED_WAITING_CAPTURE` | 認可済みで、加盟店によるキャプチャを待っています（カード決済）。 |
| `PAY_SUCCESS` | 最終的な成功。 |
| `ORDER_CLOSE` | 最終的なクローズ——注文はキャンセル、失敗、またはタイムアウトしました。 |

最終状態は `PAY_SUCCESS` と `ORDER_CLOSE` のみです。

## 注文がタイムアウトしました——`TIMEOUT_CLOSE` と `TIMEOUT_CHANNEL_CLOSE` の違いは？

どちらもタイムアウトでクローズされた注文の失敗コードです。**ユーザーがどこで離脱したか**を
教えてくれます：

| 失敗コード | 何が起きたか |
| - | - |
| `TIMEOUT_CLOSE` | ユーザーが Waffo のチェックアウト／決済ページで決済を放棄しました——決済サービスへのリクエストは一度も開始されていません。 |
| `TIMEOUT_CHANNEL_CLOSE`（"Timeout waiting for channel response"） | 決済または認証のリクエスト（例：3DS やウォレットへのリダイレクト）はすでに開始されていましたが、注文がタイムアウトする前に結果が返ってきませんでした。 |

この区分をコンバージョンファネルの分析に使ってください：`TIMEOUT_CLOSE` は認可開始前の離脱、
`TIMEOUT_CHANNEL_CLOSE` は開始後にフローが停滞したことを意味します。Waffo がリクエストが
開始されたかどうかを判定できない場合、注文は `TIMEOUT_CLOSE` にフォールバックします。この区分は
すべての決済手段に適用されます。過去の注文は元のコードを保持します。

## 銀行振込／店頭支払いでは、なぜ通知が 2 回来るのですか？

ユーザーがチェックアウトセッションの外で支払う決済手段——銀行振込／バーチャルアカウント（VA）と
店頭支払い（OTC）——は、2 段階で報告されます：

1. **受付** — 注文作成後、受付結果を受け取ります。これは**最終的な決済ステータスではありません**：
   ユーザーはまだ支払っていません。
2. **決済結果** — 最終的な通知は、ユーザーが銀行、ATM、または店頭で支払いを完了した後にのみ届きます。

両者の間隔は長くなることがあり、自動クローズ時間は決済手段ごとに異なります。同期型の決済手段と
まったく同様に、`PAY_SUCCESS` / `ORDER_CLOSE` のみを最終として扱ってください。

## Webhook が届きませんでした。何を確認すべきですか？

1. `notifyUrl` は \*\*HTTPS（TLS 1.2 以上）\*\*で、公開インターネットから到達可能でなければ
   なりません。
2. `X-SIGNATURE` ヘッダーを **Waffo の公開鍵**で検証してください——そして、エンドポイントが
   正当なリクエストを拒否していないことを確認してください。
3. 処理後に `{"message": "success"}` を返してください。Waffo が `failed` または `unknown` を
   受け取った場合、Waffo は翌日にわたって分散されたバックオフスケジュールで通知を再送します——
   スケジュールは[Webhook 再送](/docs/ja/developer-docs/webhook/retry)を参照してください。
4. 調査中は Order Inquiry で注文状態を取得し、業務フローが止まらないようにしてください。

## 待つのではなく Order Inquiry を呼び出すべきなのはどんなときですか？

* 想定した時間内に Webhook が届かなかったときの**照合用フォールバック**として。
* リクエストで `Exxxxx` の不明エラーを受け取ったとき——最終的な `PAY_SUCCESS` または
  `ORDER_CLOSE` を得るまで照会を再試行してください。
* バッチ照合ジョブにおいて。

Order Inquiry と Webhook は同じ注文状態を返します。最終ステータスについて食い違うことは
ありません。

## 注文作成が失敗しました。それでも通知は届きますか？

はい。`PAYMENT_NOTIFICATION` は決済が**完了または失敗**したときに送信されます——失敗した注文も
成功した注文とまったく同様に通知されるため、同期的な作成レスポンスだけに依存してフローを
構築しないでください。

通知はそのレスポンスよりも情報が豊富です：

| 参照する場所 | 得られるもの |
| - | - |
| `/api/v1/order/create` レスポンス | `paymentRequestId`、`merchantOrderId`、`acquiringOrderId`、`orderStatus`、`orderAction`（ステーブルコイン注文では `x402Info` も） |
| `PAYMENT_NOTIFICATION`（および Order Inquiry） | **`orderFailedReason`** を含む完全な注文オブジェクト——`orderFailedCode` と `orderFailedDescription` を持つ JSON 値 |

つまり、拒否された注文の失敗理由は、作成レスポンスではなく、通知と Order Inquiry で取得できます。
通知は `paymentRequestId` または `merchantOrderId` でお客様側の記録と照合してください。どちらも
そのまま返されます。他の Webhook と同じ方法で応答してください——
[イベントタイプ一覧](/docs/ja/developer-docs/webhook/event-types)を参照してください。

## 注文作成後、ユーザーはいつまで支払えますか？

`orderExpiredAt` は省略可能です。省略すると、加盟店契約のデフォルト有効期限が適用されます。
これが制御するものは、見た目より狭い範囲です：

* ユーザーが**チェックアウト画面で注文を送信**できる期間を決めます（UTC+0 でなければなりません）。
* 注文が決済手段に送信された後は、有効期限はお客様の値ではなく**その決済手段**によって決まります。
  少数の決済手段は加盟店からのチャネル側有効期限を受け付けます——Merchant Portal の Payin ページに
  決済手段ごとの有効期限の挙動が表示されます。
* すでに経過した時刻を渡すと、作成時に `A0034`（"the order expiry time provided by the merchant
  has expired"）で拒否されます。

実務上の影響：お客様側のクローズ時間と決済手段のクローズ時間は同じ時計ではありません。そのため、
Waffo が注文をクローズした後に決済が着地することがあります——その場合の対処はこのページの最後の
セクションを参照してください。

## オフラインまたは銀行振込の注文が数時間保留のままです。キャンセルすべきですか？

いいえ。店頭支払い（OTC）およびバーチャルアカウント／銀行振込の決済では、ユーザーは
チェックアウトセッションの外で支払うため、長い保留期間は失敗の兆候ではなく正常です——そして
自動クローズ時間は決済手段ごとに異なります。

経過時間から失敗を推測しないでください。また、注文がまだオープンな間にお客様側で購入を解放したり
取り消したりしないでください：最終通知を待つか、Order Inquiry をポーリングしてください。最終状態は
`PAY_SUCCESS` と `ORDER_CLOSE` のみです。

## 同じリクエストを同時に 2 回送信してエラーになりました。どちらかは通ったのですか？

同時実行の拒否は保護であって、業務上の失敗ではありません。同じ注文を 2 つのリクエストで並行して
作成すると、2 つの注文を作成する代わりに `A0040`（"the order cannot be created concurrently"）が
返されます。

次のように対処してください：

1. **注文ごとに呼び出しを直列化する** — 並行した再試行ではなく、一度に注文ごと 1 つの進行中
   リクエストにします。
2. \*\*状態を推測せず、確定させる。\*\*何かを判断する前に Order Inquiry を呼び出して、注文の実際の
   状態を確認してください。
3. 元のリクエストを再試行するときは、同じ `paymentRequestId` を再利用してください——これが
   冪等性キーです。`A0011` と `E` クラスの不明ステータスの処理については
   [エラーコードクイックリファレンス](/docs/ja/developer-docs/tools-and-references/developer-tools/error-codes)
   を参照してください。

## ユーザーは支払ったと言っていますが、注文は失敗またはタイムアウトと表示されています

まれに、Waffo の注文がすでにタイムアウトでクローズされた後に、決済手段側で決済が完了することが
あります（「先に失敗、後で成功」）。対処方法：

* \*\*ユーザーの支払いスクリーンショットを根拠に履行しないでください。\*\*Webhook または Order Inquiry
  が `PAY_SUCCESS` を報告したときにのみ履行してください。
* 注文 ID を添えて Waffo サポートにこのケースを報告してください。Waffo が決済手段側と注文を
  照合し、その後、決済がお客様に確認されるか、引き落とされた金額がユーザーに返還されます。
* 取引を特定するためにユーザーに追加の詳細を求める場合があるため、ユーザーが提供できる情報——
  支払い時刻、金額、決済手段の取引参照番号——を集めておいてください。


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