<!-- Source: https://docs.infraio.xyz/ja/concepts/orders -->
<!-- Last updated: 2026-10-04 -->

# 注文

[CheckoutSession](https://docs.infraio.xyz/ja/concepts/sessions) がバイヤーが目にするものなら、
**Order** は *あなた* が気にするものです。次の永続的レコードです:

- 何が買われていたか (行明細)
- いくら未払いで、実際にいくら支払われたか
- 未処理 / 適用済みの返金
- あなたの外部参照 (`external_ref`) — 通常は独自の注文 ID で、
  Order に保存され `GET /b2b/v1/orders/{id}` で返されます
  (Webhook ペイロードにはエコーされません — 下記参照)

注文に行明細は必須ではありません。`items` の代わりに `amount` を送ると金額だけを請求できます (請求書、デポジット、任意金額の支払いリンクなど)。どちらか一方だけを送ってください。

CheckoutSession は PaymentIntent の 1 つが精算するか TTL が切れると
死にます。Order は永遠に残ります。

## Order が作成されるタイミング

`POST /b2b/v1/checkout-sessions/quick` を呼ぶと、InfraIO Pay は
新しい Order *と* 新しい CheckoutSession を **両方** 1 つのトランザクション
で作成します。既に Order があってチェックアウトをリトライしたい場合
(例: バイヤーが放棄した後) は、代わりに
`POST /b2b/v1/checkout-sessions` を使って既存の注文に新しいセッションを
紐付けてください — 監査トレイルを保持します。

## ライフサイクル

```mermaid
stateDiagram-v2
    [*] --> PENDING: order created
    PENDING --> PAID:              full payment settled
    PENDING --> PARTIAL_PAID:      underpayment settled
    PENDING --> CANCELED:          session expired or canceled
    PARTIAL_PAID --> PAID:         merchant resolves OR remainder paid
    PAID --> PARTIALLY_REFUNDED:   partial refund executed
    PAID --> REFUNDED:             full refund executed
    PARTIALLY_REFUNDED --> REFUNDED: subsequent refund covers the rest
    PAID --> [*]
    REFUNDED --> [*]
    CANCELED --> [*]
```

| 状態 | 意味 |
| --- | --- |
| `PENDING` | CheckoutSession が live で未解決。 |
| `PAID` | 全額が精算。**Webhook `payment.settled` がここで発火。** フルフィルメント可。 |
| `PARTIAL_PAID` | 資金は届いたが合計より少ない。下記「過少支払い」を参照。 |
| `CANCELED` | セッション期限切れ、またはマーチャントがキャンセル。`metadata.canceled_reason` で理由 (`payment_timeout`, `merchant_canceled`, …) を説明。 |
| `REFUNDED` | 支払い額がすべて返金された。 |
| `PARTIALLY_REFUNDED` | 一部の返金が実行されたが、残りは支払い済みのまま。 |

> **Note:**
>
> **フルフィルメントロジックを切り替える対象状態は `PAID`** で、
> CheckoutSession の `COMPLETED` ではありません。`payment.settled`
> Webhook が正式なシグナルです。

## `external_ref` フィールド

セッション作成時に `external_ref` を含められます (最大 255 文字までの
任意の文字列 — 通常は独自の注文 ID)。これはパイプライン全体を通じて
スレッドされます:

- Order に保存
- マーチャントダッシュボードでサポート検索用に表示
- `GET /b2b/v1/orders/{id}` で返却されるので、Webhook ハンドラが
  `payment.settled` 受信後に取得可能

> **Warning:**
>
> Webhook ペイロードには `external_ref` は含まれ **ません**。`payment.*`
> Webhook を自社のレコードにマップし戻すには、ペイロードから
> `order_id` を取り、`GET /b2b/v1/orders/{id}` で注文を取得してください。

## 過少支払い

バイヤーのオンチェーン送金が注文合計に届かずに確定すると、Order は
`PARTIAL_PAID` に移ります。3 つの選択肢があります:

1. **受け入れて解決。** 注文を `PAID` に遷移させ、`order.resolved` を
   発火。これは REST API では利用できないため、セルフサーブフローでは
   オプション 2 (残額を回収) を使用してください。
2. **残額を待つ。** 同じ Order に対して `amount_due` = 残額の新しい
   CheckoutSession を作成します。バイヤーが差額を支払うと、それが
   精算したときに Order は `PAID` に移ります。
3. **キャンセルして返金。** 部分額を返金して Order をキャンセル。
   チェーン手数料はバイヤーの責任です。

## 返金

返金は別の API サーフェスで、別のコンセプトページです。
[コンセプト → 返金](https://docs.infraio.xyz/ja/concepts/refunds) を参照してください。

## API エンドポイント

| メソッド | パス | 備考 |
| --- | --- | --- |
| `POST` | `/b2b/v1/orders` | セッションなしで Order を作成 (レア) |
| `GET` | `/b2b/v1/orders/:order_id` | 行明細 + 支払い履歴付きで注文を読み取り |
| `PATCH` | `/b2b/v1/orders/:order_id/cancel` | 未払い注文をキャンセル |
| `PATCH` | `/b2b/v1/orders/:order_id/reopen` | 自動キャンセル済み (`payment_timeout`) 注文を再オープン |

## 次に

- [コンセプト → セッション](https://docs.infraio.xyz/ja/concepts/sessions) — Order を包む
  バイヤー向けシェル。
- [コンセプト → 返金](https://docs.infraio.xyz/ja/concepts/refunds) — 返金状態と手動の
  オンチェーン送信ステップ。
- [Webhook → 概要](https://docs.infraio.xyz/ja/webhooks/overview) — Order のライフサイクル
  中に発火する全イベント。