> ## 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 の決済注文、サブスクリプション、返金のステータス遷移について解説します。

## 注文ステータスの遷移

```mermaid theme={null}
stateDiagram-v2
    [*] --> PAY_IN_PROGRESS
    PAY_IN_PROGRESS --> AUTHORIZATION_REQUIRED
    PAY_IN_PROGRESS --> PAY_SUCCESS
    PAY_IN_PROGRESS --> ORDER_CLOSE
    AUTHORIZATION_REQUIRED --> AUTHED_WAITING_CAPTURE
    AUTHORIZATION_REQUIRED --> PAY_SUCCESS
    AUTHED_WAITING_CAPTURE --> PAY_SUCCESS
    PAY_SUCCESS --> ORDER_PARTIALLY_REFUNDED
    PAY_SUCCESS --> ORDER_FULLY_REFUNDED
    ORDER_CLOSE --> [*]
    PAY_SUCCESS --> [*]
```

## 注文ステータス一覧

| ステータス                    | 説明                                    | 最終状態 |
| ------------------------ | ------------------------------------- | ---- |
| `PAY_IN_PROGRESS`        | 注文を受け付け、ユーザーが決済中です                    | いいえ  |
| `AUTHORIZATION_REQUIRED` | 決済手段にユーザーの認可が必要です(電子ウォレットなど)          | いいえ  |
| `AUTHED_WAITING_CAPTURE` | 認可済み、キャプチャ確認待ち(カード決済。加盟店側のキャプチャ確認が必要) | いいえ  |
| `PAY_SUCCESS`            | 決済成功                                  | はい   |
| `ORDER_CLOSE`            | 注文クローズ(キャンセル、失敗、タイムアウト)               | はい   |

## サブスクリプションのステータス

| ステータス                    | 説明                     | 対応                               |
| ------------------------ | ---------------------- | -------------------------------- |
| `AUTHORIZATION_REQUIRED` | ユーザー認可が必要(電子ウォレットのケース) | `subscriptionAction` URL にリダイレクト |
| `IN_PROGRESS`            | ユーザーがサブスクリプションを確認中     | Webhook を待機                      |
| `ACTIVE`                 | サブスクリプション有効、正常に課金中     | `subscriptionId` を保存             |
| `CLOSE`                  | クローズ(タイムアウトまたは失敗)      | 必要に応じて再開                         |
| `MERCHANT_CANCELLED`     | 加盟店によるキャンセル            | —                                |
| `USER_CANCELLED`         | ユーザーによるキャンセル           | ローカルレコードを更新                      |
| `CHANNEL_CANCELLED`      | チャネルによるキャンセル           | ユーザーに通知                          |
| `EXPIRED`                | 有効化されずに期限切れ            | 必要に応じて再開                         |

## 返金ステータス

| ステータス                      | 説明     |
| -------------------------- | ------ |
| `REFUND_IN_PROGRESS`       | 返金処理中  |
| `ORDER_PARTIALLY_REFUNDED` | 一部返金完了 |
| `ORDER_FULLY_REFUNDED`     | 全額返金完了 |
| `ORDER_REFUND_FAILED`      | 返金失敗   |

## ベストプラクティス

<Tip>
  **Webhook を唯一の信頼できる情報源として扱ってください**: リダイレクト URL はユーザー体験のためだけのものであり、決済結果の判定には使用しないでください。
</Tip>

1. **中間ステータスの扱い**: `PAY_IN_PROGRESS` の注文を自動的にクローズせず、Webhook を待つか能動的に照会してください
2. **冪等な処理**: Webhook は複数回配信される可能性があります。処理ロジックが冪等であることを確認してください。詳しくは [冪等性](/docs/ja/developer-docs/core-concepts/idempotency) を参照してください
3. **不明なステータス**: エラーコード `E0001` が発生した場合は、元の `paymentRequestId` で照会し、注文を自動クローズしないでください。完全な処理フローは [エラー処理](/docs/ja/developer-docs/core-concepts/error-handling) を参照してください