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

# 各ステータスの注文に対して何ができますか？

> ほとんどのマーチャントが目にしない 2 つのステータスを含む注文ステータス一覧、どのステータスがキャンセル・キャプチャ・返金を受け付けるか、注文が AUTHORIZATION_REQUIRED にとどまる理由、クローズ理由がどこに書かれるか、決済手段がすでに資金を受け取っている場合のキャンセルの動作、オーソリ済みカード決済をキャプチャするルール。

ステータス一覧そのものは
[決済ライフサイクルと注文ステータス](/docs/ja/developer-docs/core-concepts/payment-lifecycle)と
[データリファレンス](/docs/ja/developer-docs/tools-and-references/references/data-reference)で公開されています。
このページはその*運用面*の半分、つまり各ステータスがどのアクションを受け付けるか、そして注文が想定した状態に
ないときに 3 つの書き込みエンドポイント（キャンセル、キャプチャ、返金）が何をするかを扱います。

| ページ | 用途 |
| - | - |
| [決済結果の確認](/docs/ja/support/payment-results-faq) | 各ステータスが何を*意味する*か、および結果の確認方法 |
| [タイムアウトと結果が確定するタイミング](/docs/ja/support/payment-timeout-and-finality-faq) | 結果がまだ変わりうるか、タイムアウトに強い連携 |
| **このページ** | どのステータスでどのアクションが許可されるか、許可されない場合のエラー |

## 公開されている一覧にないステータスはありますか？

2 つあります。どちらも、対処すべきものというより、紛らわしい観察結果を説明するものとして知っておく価値があります。

| ステータス | 内容 |
| - | - |
| `CAPTURE_IN_PROGRESS` | 貴社が要求したキャプチャが実行中。オーソリ済み状態と `PAY_SUCCESS` の間にあり、キャプチャの再呼び出しを受け付けます |
| *（決済手段に何も届く前の前段ステータス）* | 受理されたが決済の試行がまだ存在しない注文は、**`AUTHORIZATION_REQUIRED` として報告されます**。API 上に別の値はありません |

2 つ目はマーチャントからよく尋ねられる質問への答えなので、はっきり述べる価値があります。
`AUTHORIZATION_REQUIRED` は\*「決済手段がユーザーの承認を待っている」*と*「この注文ではまだ何も起きていない」\*の
両方をカバーします。ステータスだけでこれらを区別することはできません。

## 注文が `AUTHORIZATION_REQUIRED` で止まっています。ユーザーが WebView を閉じたのですか？

そうかもしれませんが、ステータスはそれを教えてくれませんし、それが唯一の説明でもありません。
`AUTHORIZATION_REQUIRED` は*結果が返ってきていない*ことを意味し、次のすべてと矛盾しません。

* ユーザーが決済ページをまったく開かなかった。
* ユーザーが開いて放棄した — WebView を閉じた、アプリを終了した、離れた。
* ユーザーがまだそのページにいて、認証の途中である。
* 決済の試行がまだ行われていない。

したがってこれは診断ではなく、特にユーザーに報告すべき失敗の証拠では**ありません**。正しい対処はどの場合も同じです。
そのままにしておき、注文が期限に達するのを待ち、Webhook または Order Inquiry から結果を受け取ってください。
タイマーで自分でクローズしないでください。
[タイムアウトと結果が確定するタイミング](/docs/ja/support/payment-timeout-and-finality-faq)を参照してください。

ページが開かれたかどうかを知ることが運用上重要な場合、それは注文ステータスではなく、貴社自身のフロントエンド計測の問題です。

## どのステータスが最終で、自社の結果として保存できますか？

最終のステータスは 2 つです：**`PAY_SUCCESS`** と **`ORDER_CLOSE`**。それ以外はすべて遷移中であり、
遷移中のステータスの注文はまだ動きえます。

`PAY_SUCCESS` と `ORDER_CLOSE` が互いに入れ替わることはありません。注文が一度クローズされると、後から決済手段の
成功報告が届いても再オープンされ**ず**、`PAY_SUCCESS` に書き換えられることも**ありません**。一度成功すれば、
成功のままです。したがって、最終ステータスを業務上の結果として永続化できます。

永続化して*安全でない*唯一のものは、最終ステータスが**資金**に関してそれ以上何も起こりえないことを意味するという
思い込みです。成功した注文でも後から返金や異議申し立てが起こりえますが、そのどちらも `orderStatus` を変更しません。
下記の返金の質問を参照してください。

## 各ステータスの注文に対して何ができますか？

| ステータス | キャンセル | キャプチャ | 返金 |
| - | - | - | - |
| 前段ステータス / 決済の試行がまだない | 可 | 不可 | 不可 |
| `PAY_IN_PROGRESS` | 可 | 不可 | 不可 |
| `AUTHORIZATION_REQUIRED` | 可 | 不可 | 不可 |
| `AUTHED_WAITING_CAPTURE` | 可 | **可** | 不可 |
| `CAPTURE_IN_PROGRESS` | 不可 | 可（冪等な再実行） | 不可 |
| `PAY_SUCCESS` | 不可 — `A0013` | 不可 | **可** |
| `ORDER_CLOSE` | 可（何もしない） | 不可 | 不可 |

2 つの境界は注意して読んでください。連携が誤りやすいのはここです。

* **返金は `PAY_SUCCESS` からのみ可能です。**「保留中の注文を返金する」ことはできません。資金が着金していないなら、
  必要なアクションはキャンセルです。
* **キャプチャしないオーソリを解放する方法はキャンセルです。** オーソリ、キャプチャ、その後の返金という流れよりも
  実質的に優れています。

## キャンセルを呼び出したら拒否されました。各エラーの意味は何ですか？

| 状況 | コード |
| - | - |
| すでに決済が成功している | `A0013` Order cannot be cancelled due to payment already success |
| 決済手段がキャンセルをサポートしていない | `A0015` Order cannot be cancelled due to payment channel not supported |
| 決済手段がキャンセルを拒否した | `A0016` Order cannot be cancelled due to payment channel rejection |
| 注文がキャンセルできないステータスにある | Order status is invalid to proceed |
| 注文が存在しない、または ID が一致しない | Order not found / id mismatch |
| キャンセル呼び出しが同時に 2 件 | 並行性エラー — リトライしてください |

それぞれへの対処：

* **`A0013` はリトライすべきエラーではありません。** ユーザーは支払っています。履行したくない場合のアクションは
  キャンセルではなく返金です。
* **`A0015` はリクエストではなく決済手段についての事実です。** キャンセル操作をまったく持たない決済手段もあります。
  その場合、未払いの注文が終わる方法は期限切れです。「キャンセルは利用できないかもしれない」前提で設計し、
  期限切れに任せてください。
* **`A0016` は決済手段側から返ってきたものです。** 1 回のリトライは試す価値がありますが、繰り返すようなら止めて、
  注文を期限切れにさせてください。
* **すでにクローズされた注文のキャンセルは成功し**、何もしません。そのため、ステータスを先に確認しなくても
  クリーンアップジョブから安全に呼び出せます。

注文を特定するには `paymentRequestId` または `acquiringOrderId` のいずれかに加えて `merchantId` を送信できます。
どちらの ID も送らないとバリデーションエラーになります。

## キャンセル後、ユーザーは決済手段のページでまだ支払えますか？

キャンセルは注文を `ORDER_CLOSE`（最終ステータス）にし、決済手段側にもキャンセルを要求します。その時点から注文は
完了できません。後から届く成功報告は適用されないため、注文が知らないうちに支払済みに変わることはありません。

キャンセルが保証できないのは、**ユーザーの目の前ですでに開いているサードパーティの決済ページ**が入力の受け付けを
止めることです。決済手段がキャンセルをまったくサポートしていない場合（`A0015`）、定義上、相手側では何もキャンセル
されていません。したがって「ユーザーはまだ支払えるか」への正直な答えは、*資金を渡すことはできるかもしれないが、
それが完了した注文になることはない*、です。その期間に動いた資金は履行のケースではなく回収のケースであり、
対処方法は[タイムアウトと結果が確定するタイミング](/docs/ja/support/payment-timeout-and-finality-faq)に記載されています。

実務上のルール：販売しないと決めたときにキャンセルしてください。ユーザーがまだ見ているチェックアウトを閉じる手段として
キャンセルを使わないでください。

## 「短い期限を設定し、過ぎたらキャンセルする」は良い設計ですか？

妥当な設計ですが、1 つの訂正と 1 つの注意点があります。

* **訂正：** キャンセルの呼び出しは不要です。支払われないまま期限に達した注文は自動的にクローズされ、貴社に通知されます。
  その後に自前のキャンセルを追加しても無害ですが（クローズ済み注文では何もしません）、注文を終わらせているのは
  それではありません。
* **注意点：** 短い期限は決済手段自身の期間を短くしませんし、相手側で遅れて支払いが行われるのを止めません。したがって
  3 分の期限は 3 分の*チェックアウト*をもたらすものであり、その後に資金が動かないという 3 分の保証ではありません。

本当に短い期間が業務上必要な場合は、期限を設定し、**かつ**遅延支払いの回収経路を構築してください。チェックアウトが
有効に見えなくなるだけでよいなら、期限だけで十分です。

## 注文は設定した期限ちょうどにクローズされますか？

それに近いですが、秒単位ではありません。クローズは定期的なスイープで行われるため、注文は名目上の期限の後も
短い間は技術的に開いたままになることがあり、大量の場合は期限を迎えた注文のまとまりが次のパスに持ち越されることがあります。
クローズ前に決済手段が確認され、すでに決済が進行中の注文は、決済の下でクローズされるのではなくそのまま残されます。

これが意味すること：

* **「注文がクローズされたこと」を時計として使わないでください。** 履行ロジックに期限が必要なら、送信した期限に対して
  自前のタイマーを使ってください。注文ステータスは*時刻*ではなく*結果*を知るために使ってください。
* **わずかに遅れたクローズをインシデントとして扱わないでください。** それが設計です。
* **過去の期限は拒否されず、破棄されます。** 注文作成時に `orderExpiredAt` がすでに過去である場合、その値は破棄され、
  注文には決済手段のデフォルト期限が適用されます。つまり、貴社側の時計のバグは大きな音を立てて失敗するのではなく、
  意図より長く開いたままの注文を生みます。送信前にタイムスタンプを確認してください。

`orderExpiredAt` をまったく送信しない場合でも注文は最終的にクローズされますが、その時刻は貴社が設定した値ではなく、
依存すべき値でもありません。期間が業務上重要な場合は常に明示的な期限を送信してください。

## タイムアウトで注文がクローズされたときに通知は届きますか？

はい。クローズされた注文は通常の決済通知 `PAYMENT_NOTIFICATION` を生成します。Order Inquiry と同じ注文構造を持ち、
`orderStatus` は `ORDER_CLOSE`、理由は `orderFailedReason` に入ります。購読すべき別の「注文期限切れ」イベントタイプは
なく、追加で有効化するものもありません。

したがって、`PAYMENT_NOTIFICATION` を処理し `orderStatus` で分岐する連携は、すでにタイムアウトによるクローズを
処理できています。受信できていない場合は Webhook の配信の問題です。
[Portal の Webhook ログ](/docs/ja/support/portal-webhook-log-faq)と
[Webhook リトライ](/docs/ja/developer-docs/webhook/retry)を参照してください。

## `orderFailedReason.orderFailedCode` をエラーコード表で調べられますか？

**いいえ。別のコード体系です。** `Axxxx` コードは、貴社の*リクエスト*が誤っているか拒否されたときに API 呼び出しが
同期的に返すものです。`orderFailedReason` の中のコードは、*注文*がなぜそのように終わったかを説明するもので、
理由指向の別の名前空間です。一方を他方の表で調べることが、マーチャントがそのコードは「存在しない」と結論づける
原因になっています。

| 手元にあるもの | それは | 調べる場所 |
| - | - | - |
| API レスポンスの `code` / `msg` | API エラーコード | [エラーコード](/docs/ja/developer-docs/tools-and-references/developer-tools/error-codes)、[API リファレンス表](/docs/ja/support/api-reference-tables) |
| クローズまたは失敗した注文の `orderFailedReason.orderFailedCode` | 注文の失敗理由 | 併せて送られる `orderFailedDescription`、および Portal → Transactions → その注文の Order Failure Description |

これを使って自動化できますか？ 部分的に、慎重に行えます。

* 頼りにできる大まかな区別で分岐**してください** — タイムアウトによるクローズは決済の拒否とは異なる業務イベントであり、
  どちらもキャンセルとは異なります。
* コードの隣に `orderFailedDescription` を必ず保存**してください**。見たことのないコードが届いたときに、読める形で
  残るのはその部分です。
* 認識できない理由を自社コードの不具合として扱う網羅的な switch を作ら**ないでください**。この集合はテストで目にする
  数個よりも大きく、決済手段の変化に伴って新しい理由が現れます。「クローズ、未払い、理由は記録済み」を既定とし、
  推測するのではなく人に通知してください。

タイムアウトの理由は 2 つに分かれます。決済手段に到達しなかった注文のものと、到達した注文のものです。実務上の違いは
[決済結果の確認](/docs/ja/support/payment-results-faq)で説明しています。

## オーソリした金額より少ない金額をキャプチャできますか？

はい。キャプチャ金額は**ゼロより大きく、オーソリ金額以下**であれば何でも構いません。オーソリの残りは保持されるのではなく
解放されます。オーソリ額を超えるキャプチャは拒否されます。

| 送信内容 | 結果 |
| - | - |
| オーソリ金額より少ない | キャプチャされ、残りは解放される |
| オーソリ金額ちょうど | キャプチャされる |
| オーソリ金額より多い | 拒否 — その金額のキャプチャはサポートされない |
| 2 回目のキャプチャ、1 回目と同じ金額 | 冪等：元の結果が返る |
| 2 回目のキャプチャ、**異なる**金額 | 冪等性の不一致として拒否（`A0011`） |
| オーソリ済み状態にない注文へのキャプチャ | 拒否 — 現在のステータスではキャプチャできない |
| 手動キャプチャに設定されていない注文へのキャプチャ | 拒否 — その注文ではキャプチャがサポートされない |

最後の行が人々を驚かせます。キャプチャは**手動キャプチャモード**で作成された注文にのみ存在します。注文作成時に
`paymentInfo.captureMode` でオプトインし、そこで受け付けられる値は `manualCapture` のみです。通常の注文は自動的に
キャプチャされ、貴社が呼び出すものはありません。

最も重要な点について、公開されているプロダクトの動作はコードと一致しています。キャプチャは実質的に**1 回限り**です。
一度キャプチャすると、たとえ一部でもオーソリの残りは解放されるため、オーソリを分割して引き出すことはできません。
従量課金には、繰り返しのキャプチャではなく、保存したトークンと定期的な請求のパターンを使用してください。
[Auth-Capture](/docs/ja/essentials/auth-capture)と[トークナイゼーション](/docs/ja/support/tokenization-faq)を参照してください。

## キャプチャの期限はどのくらいですか？

期間は、オーソリに気付いた時点ではなく、**注文が作成された時点**から丸一日単位で数えます。これはプラットフォーム全体の
単一の設定であり、すべてのマーチャントに一律に適用されます。アカウントごとに交渉されるものではなく、拒否メッセージの
文言は現在の数値を知る信頼できる手がかりではありません。これを前提に履行プロセスを設計する前に、サポートに期間を
確認してください。

期間が経過すると 2 つのことが起こり、どちらにも備えるべきです。

* **キャプチャ呼び出しが失敗し始めます。** キューに入るのではなく、サポート対象外として拒否されます。
* **オーソリは自動的に解放されます。** 期限切れのオーソリは能動的にキャンセルされるため、貴社が忘れたために顧客の
  資金が保持され続けることはありません。

したがって、オーソリは無期限に保持できる約束ではなく、キャプチャは期限のないリトライキューに置くものでもありません。
履行にキャプチャ期間より長くかかる場合は、配達時ではなく出荷時にキャプチャするか、保存したトークンを使って準備が
できたときに請求してください。

## 一部の注文で `refundExpiryAt` が空なのはなぜですか？

`refundExpiryAt` は、それ以降その注文を返金できなくなる時点です。**その決済手段に対する契約上の返金期間**から導出され、
決済が成功した時点ではなく注文の**作成日**から起算し、その日の終わりに到達します。

2 つの結果：

* 日数で表される期間は**暦日**の期間です。その日の遅い時間に作成された注文は、早い時間に作成された注文より
  実質的に使える期間がやや短くなります。境界はいずれにせよ 1 日の終わりだからです。
* 決済が成功しても時計は再スタートしません。作成からかなり後に支払われた注文は、すでに返金期間の一部を消費しています。

該当しない場合は常に空（`null`）です。

| null になる場合 | 理由 |
| - | - |
| 注文が成功していない | 返金するものがない |
| その契約で返金が許可されていない | 表現すべき期間がない |
| その契約に返金期間が設定されていない | 同上 |

したがって、`refundExpiryAt` がないことを「永久に返金可能」と読まないでください。「この注文について期限が公開されていない」
と読み、適用されるものは
[決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq)で確認し、まだ返金できる金額は返金 API の
`remainingRefundAmount` で判断してください。

## 返金は元の注文のステータスを変えますか？

いいえ。これはこのエンドポイントで最も多い誤報です。返金が `orderStatus` を書き換えることはありません。
全額返金された注文でも `PAY_SUCCESS` を報告し続けます。返金の進捗は返金記録と、注文の別の返金ステータスフィールドに
あり、決済ステータスにはありません。

貴社の帳簿が `orderStatus` をキーに返金状態を管理していると、永久に止まっているように見えます。代わりに返金記録を
キーにしてください。どの質問をどこで確認するかは
[決済手段別の返金制限](/docs/ja/support/payment-method-refund-limits-faq)にまとめられています。

***

動かないステータスで行き詰まっていますか？ `acquiringOrderId` と表示されているステータスを添えて
[サポートにお問い合わせください](mailto:support@waffo.com)。


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