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

# 注文と支払い

> 取引を追跡し、支払いライフサイクルを管理

## 概要

Waffo Pancake でのすべての購入は、**注文**と関連する**支払い**レコードを作成します。注文は顧客の購入意思を表し、支払いは実際の金銭の動きを追跡します。

***

## 注文ステータス

注文には、商品タイプに応じて異なるステータスセットがあります。

### 単発注文

| ステータス      | 説明              |
| ---------- | --------------- |
| `pending`  | 注文が作成され、支払い待ち   |
| `paid`     | 支払いが成功し、注文が完了   |
| `canceled` | 完了前に注文がキャンセルされた |

### サブスクリプション注文

| ステータス       | 説明                               |
| ----------- | -------------------------------- |
| `pending`   | サブスクリプションが作成され、初回支払い待ち           |
| `active`    | サブスクリプションが有効で、通常通り請求中            |
| `trialing`  | 顧客が無料トライアル期間中                    |
| `past_due`  | 支払いが失敗し、再試行中                     |
| `canceling` | キャンセルリクエスト済み、現在の期間終了までアクティブ      |
| `canceled`  | サブスクリプションがキャンセルされた（期間終了までアクセス継続） |
| `expired`   | サブスクリプション期限切れ                    |
| `closed`    | 未アクティブ — 支払いタイムアウト               |

***

## 支払いステータス

<CardGroup cols={3}>
  <Card title="Pending" icon="clock" color="#f59e0b">
    支払いが開始され、処理待ち。
  </Card>

  <Card title="Processing" icon="spinner" color="#3b82f6">
    支払いが処理中。
  </Card>

  <Card title="Succeeded" icon="check" color="#22c55e">
    支払いが正常に完了。
  </Card>

  <Card title="Failed" icon="xmark" color="#ef4444">
    処理中に支払いが失敗。
  </Card>

  <Card title="キャンセル済み" icon="ban" color="#6b7280">
    支払いがキャンセルされました（タイムアウト、マーチャント操作、処理前の購入者キャンセル）。
  </Card>

  <Card title="Refunded" icon="rotate-left" color="#6366f1">
    全額返金が処理された。
  </Card>

  <Card title="Partially Refunded" icon="circle-half-stroke" color="#8b5cf6">
    一部返金が処理された。
  </Card>
</CardGroup>

<Note>
  `processing` はダッシュボードに表示される場合がありますが、API や GraphQL では返されません。API が返す支払いステータスは `pending`、`succeeded`、`failed`、`canceled` です。
</Note>

<Note>
  返金ステータスは Payment の `refundStatus` フィールドで個別に追跡されます（`none` / `pending` / `refunded` / `failed`）。支払いステータスの値ではありません。
</Note>

***

## 支払い一覧

以下のカラムを持つテーブルですべての支払いを表示します：

| カラム   | 説明                                  |
| ----- | ----------------------------------- |
| 日付    | 取引タイムスタンプ                           |
| 金額    | 表示形式の文字列での支払い金額                     |
| 税額    | 取引で徴収された税金                          |
| ステータス | 現在の支払いステータス                         |
| 支払い方法 | `card`、`bank_transfer`、または `wallet` |
| 顧客    | 顧客のメールアドレス                          |
| 通貨    | ISO 4217 通貨コード                      |

### フィルタリング

| フィルター | オプション                                                                       |
| ----- | --------------------------------------------------------------------------- |
| ステータス | `pending`、`processing`、`succeeded`、`failed`、`refunded`、`partially_refunded` |
| 日付範囲  | カスタムの開始日と終了日                                                                |

***

## 支払い詳細

任意の支払いをクリックして、完全なレコードを表示できます。

### 取引情報

| フィールド      | 説明               |
| ---------- | ---------------- |
| Payment ID | UUID v4 識別子      |
| Order ID   | 関連する注文           |
| Store ID   | 支払いを受けたストア       |
| Amount     | 総支払い金額（表示形式の文字列） |
| Currency   | ISO 4217 通貨コード   |
| Status     | 現在の支払いステータス      |
| Created At | ISO 8601 タイムスタンプ |
| Updated At | ISO 8601 タイムスタンプ |

### 金額詳細

| フィールド                | 説明                 |
| -------------------- | ------------------ |
| `amount`             | 課金された合計金額          |
| `taxAmount`          | 金額のうち税額部分          |
| `settlementCurrency` | 決済に使用される通貨         |
| `settlementAmount`   | 決済通貨での金額（表示形式の文字列） |
| `refundedAmount`     | これまでに返金された合計金額     |

### 請求先情報

| フィールド          | 説明             |
| -------------- | -------------- |
| `country`      | 顧客の請求先国        |
| `state`        | 請求先の州または地域     |
| `postcode`     | 請求先郵便番号        |
| `isBusiness`   | 法人購入かどうか       |
| `businessName` | 会社名（該当する場合）    |
| `taxId`        | Tax ID（該当する場合） |

### 支払い方法

支払いは使用された方法を記録します：

| 方法            | 値               |
| ------------- | --------------- |
| クレジット/デビットカード | `card`          |
| 銀行振込          | `bank_transfer` |
| デジタルウォレット     | `wallet`        |

支払い方法固有の追加情報は `paymentMethodDetails` フィールドで利用可能な場合があります。このフィールドの構造は支払い方法によって異なります。

***

## 対応している支払い方法

<CardGroup cols={3}>
  <Card title="カード" icon="credit-card">
    クレジットカードおよびデビットカード決済。
  </Card>

  <Card title="銀行振込" icon="building-columns">
    銀行間の直接振込。
  </Card>

  <Card title="ウォレット" icon="wallet">
    デジタルウォレット決済（Apple Pay、Google Pay など）。
  </Card>
</CardGroup>

***

## 返金

返金リクエストは、チケットベースの個別ワークフローで処理されます。購入者は支払いと理由を指定して返金チケットを送信し、マーチャントがリクエストを審査して承認または却下します。

<Note>
  返金プロセス、ステータス、ポリシーの詳細は[返金](/ja/customers/refunds)ページをご覧ください。
</Note>

**主なルール：**

* 単発商品の返金は支払いから **14 日以内**にリクエストする必要があります
* サブスクリプションのキャンセルは現在の請求期間の終了時に有効になります
* 返金チケットは独自のステータスを追跡します：`pending`、`approved`、`rejected`、`processing`、`succeeded`、`failed`

***

## API リファレンス

### 注文の作成

注文は2ステップのチェックアウトセッションフローで作成します：

**ステップ1：チェックアウトセッションを作成**（API Key または Store Slug 認証）

```bash theme={"system"}
curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "store-uuid",
    "productId": "product-uuid",
    "productType": "onetime",
    "currency": "USD"
  }'
```

レスポンスは `sessionId` と `checkoutUrl` を返します。チェックアウトセッションの有効期限は7日間で、商品バージョンと価格がロックされます。

**ステップ2：注文を作成**（API Key 認証）

<CodeGroup>
  ```bash 単発注文 theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/onetime-order/create-order \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "checkoutSessionId": "session-uuid",
      "billingDetail": {
        "country": "US",
        "isBusiness": false,
        "state": "CA"
      }
    }'
  ```

  ```bash サブスクリプション注文 theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/subscription-order/create-order \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "checkoutSessionId": "session-uuid",
      "billingDetail": {
        "country": "US",
        "isBusiness": false,
        "state": "CA"
      }
    }'
  ```
</CodeGroup>

両方のエンドポイントは `checkoutUrl` を返し、購入者はそのURLにリダイレクトされて支払いを完了します。

### 支払いの照会

GraphQL エンドポイントを使用して支払いレコードを照会できます：

```graphql theme={"system"}
query {
  payments(storeId: "store-uuid", limit: 20) {
    id
    orderId
    amount
    currency
    status
    paymentMethod
    amountDetails {
      amount
      taxAmount
      settlementCurrency
      settlementAmount
      refundedAmount
    }
    billingDetail {
      country
      state
      postcode
      isBusiness
      businessName
      taxId
    }
    createdAt
  }
}
```

<Tip>
  すべての金額は表示形式の文字列です。例えば、USD で `"29.00"` は \$29.00 を意味します。JPY のようなゼロ小数点通貨の場合、`"4500"` は 4500 円を意味します。
</Tip>