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

# 返金エンドポイント

> REST + GraphQL で返金をリクエスト・照会する

返金エンドポイントにより、マーチャントは成功済みの支払いに対して返金を発行できます。返金は **返金チケット**（リクエスト）と **返金レコード**（PSP 確認後に書き込まれる実行結果）の 2 つのモデルで構成されます。

***

## ビジネスルール

<Note>
  * 返金は元の支払い成功から **14 日以内** にリクエストする必要があります
  * 返金額は **部分返金**（`> 0` かつ `≤ payment.amount`）が可能ですが、支払いと**同じ通貨**を使用する必要があります
  * 元の支払いが **PSP によって完全に確定済み**である必要があります — payment webhook 到着直後の返金呼び出しは一時的に失敗することがあります。数秒後にリトライしてください
  * pending または succeeded の返金がすでに存在する支払いに対しては**別の返金チケットを作成できません**
  * マーチャントがサーバーサイドの API Key で返金を送信すると、チケットは**自動承認**され直接 processing に遷移します — 手動レビューはありません
</Note>

***

## 返金チケットステータス値

| ステータス        | マーチャント視点の意味                          |
| ------------ | ------------------------------------ |
| `pending`    | Waffo レビュー待ち（customer が自主発起した場合のみ表示） |
| `approved`   | 承認済み、まもなく PSP へディスパッチ                |
| `rejected`   | 拒否 — GraphQL で `rejectReason` を確認    |
| `processing` | PSP へディスパッチ済み、上流完了待ち                 |
| `succeeded`  | customer へ資金返還済み                     |
| `failed`     | PSP が失敗を返した — 再レビュー後に再提出可能           |

<Tip>
  マーチャント発起の返金は `pending` と `approved` を**スキップ**し、作成直後に `processing` として表示されます。
</Tip>

***

## ビジネス側識別子 — ビジネスレコードを紐付ける

2 つの作成エンドポイントで、それぞれビジネス側識別子（最大 **128 文字**）をオプションで付加できます。同一ペイロード上で両者が曖昧なく共存できるよう、対外的にはフラットなキー名を採用しています:

| 作成エンドポイント                     | リクエストボディフィールド                    | 永続化先                                                          |
| ----------------------------- | -------------------------------- | ------------------------------------------------------------- |
| `checkout/create-session`     | `orderMerchantExternalId`        | `orders.merchant_external_id`（初回支払いとサブスク更新が同じ値を継承）            |
| `refund-ticket/create-ticket` | `refundTicketMerchantExternalId` | `refund_tickets.merchant_external_id`（PSP 成功後、refund レコードへ継承） |

エンドツーエンドの伝播（リクエストボディ、webhook ペイロード、GraphQL 型の 3 箇所で同じフラットな双 key 名を使用）：

```
checkout/create-session         (リクエスト: orderMerchantExternalId)
                                    │
                                    ├──► OnetimeOrder / SubscriptionOrder . orderMerchantExternalId
                                    ├──► Payment                          . orderMerchantExternalId   (初回 + サブスク更新)
                                    │
refund-ticket/create-ticket     (リクエスト: refundTicketMerchantExternalId)
                                    │
                                    ├──► RefundTicket                     . refundTicketMerchantExternalId
                                    │
                                    └──► Refund は両方を保持:
                                         • orderMerchantExternalId           (元の注文から継承)
                                         • refundTicketMerchantExternalId    (元の返金チケットから継承)
```

これらの識別子は冪等性キー**ではありません** — Waffo は一意性を強制しません。同じ reference を複数のレコードに付加可能で、一意性の確保はあなたの責任です。

リクエストボディ、webhook ペイロード、GraphQL の 3 箇所で同じフィールド名を使用するため、checkout / refund-ticket 作成時に書き込んだ値をそのままの名前で読み戻せます。

これらの識別子で Payments、Refunds、Refund Tickets を GraphQL から**クエリ**できます — [GraphQL Orders & Payments](/ja/api-reference/endpoints/graphql/orders-and-payments) ガイドを参照。

***

## エンドポイント

<CardGroup cols={2}>
  <Card title="返金チケットの作成" icon="ticket" href="/ja/api-reference/endpoints/refunds/create-refund-ticket">
    成功した支払いの返金をリクエスト。全額・部分返金に対応。
  </Card>

  <Card title="返金チケットの再送信" icon="rotate" href="/ja/api-reference/endpoints/refunds/resubmit-refund-ticket">
    拒否または失敗した返金チケットを修正して再送信。
  </Card>
</CardGroup>

<Tip>
  [GraphQL](/ja/api-reference/endpoints/graphql/orders-and-payments) を使用して返金チケットと実行された返金レコードを照会します。`Refund` では 2 つのビジネス番号をフラットフィールドで公開しています：`refund.orderMerchantExternalId` と `refund.refundTicketMerchantExternalId`（webhook ペイロードと同名）。実行された返金を返金チケットのビジネス番号でフィルタリングするには `refunds(filter: { refundTicketMerchantExternalId: ... })` を使用します。
</Tip>