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

# 返金チケットの作成

> 成功した支払いに対する返金をリクエスト

`POST /api/actions/refund-ticket/create-ticket`

**認証：** マーチャント API Key（サーバー間）。

## リクエストボディ

| フィールド                            | 型      | 必須 | 説明                                                |
| -------------------------------- | ------ | -- | ------------------------------------------------- |
| `paymentId`                      | string | 必須 | 返金対象の支払い Short ID（例：`PAY_6eYCunG3IMmIgcQOnaXdoA`） |
| `reason`                         | string | 必須 | 自由テキストの理由（customer / dashboard 表示）                |
| `requestedAmount.amount`         | string | 必須 | 表示形式の返金額（例：`"10.50"`）、`> 0` かつ `≤ payment.amount` |
| `requestedAmount.currency`       | string | 必須 | ISO 4217 コード、支払い通貨と一致する必要あり                       |
| `refundTicketMerchantExternalId` | string | 任意 | マーチャント業務側の返金チケット識別子（最大 128 文字）                    |

## 成功レスポンス (200)

```json theme={"system"}
{
  "data": {
    "ticket": {
      "id": "TKT_3bVzrkD0FJjFdZNLk8Ualx",
      "status": "processing",
      "subjectId": "PAY_6eYCunG3IMmIgcQOnaXdoA",
      "refundTicketMerchantExternalId": "REF-2026-00891"
    }
  }
}
```

マーチャントが API Key で submit すると、チケットは自動承認され、すぐに `processing` へ移行します。

## エラーレスポンス

> **リトライポリシー**：4xx は一切リトライしない — リクエストを修正してから再送信。5xx は指数バックオフでリトライ（5s 開始、最大 3 回）。

| ステータス | `errors[0].message`                                             | 意味                                                                                  | 推奨処理                           |
| ----- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------ |
| 400   | `Missing required field: <name>`                                | 必須フィールド欠落（`paymentId`、`reason`、`requestedAmount.amount`、`requestedAmount.currency`） | ボディを修正して再送信                    |
| 400   | `Expected format: PAY_xxx, got "..."`                           | `paymentId` Short ID のデコード失敗                                                        | `paymentId` フォーマットを修正して再送信     |
| 400   | `Invalid requestedAmount.amount format`                         | 金額文字列が解析できない                                                                        | 表示形式（`"10.50"` など、最小単位ではない）を使用 |
| 400   | `refundTicketMerchantExternalId must be at most 128 characters` | 値が 128 文字を超過                                                                        | 128 文字以内に短縮                    |
| 401   | `Unauthorized`                                                  | API Key 署名が無効                                                                       | 認証ヘッダーを確認                      |
| 404   | `Payment not found`                                             | 支払いが存在しないか、ストアに属していない                                                               | `paymentId` を確認                |
| 409   | `Payment status is X, must be succeeded`                        | 元の支払いが `succeeded` 状態ではない                                                           | リトライしない — 支払いが成功していない          |
| 409   | `Payment is not yet fully processed by PSP, please retry later` | PSP 確認の書き戻しが未完了                                                                     | 5–30 秒後にリトライ（一時的）              |
| 409   | `Refund period expired (X days, max 14)`                        | 14 日窓を超過                                                                            | リトライしない — 返金不可                 |
| 409   | `Requested amount must be greater than 0`                       | 金額が ≤ 0                                                                             | 金額を修正して再送信                     |
| 409   | `Requested amount exceeds payment amount`                       | 金額が `payment.amount` を超過                                                            | 金額を修正して再送信                     |
| 409   | `Currency mismatch: requested X, payment Y`                     | 通貨が支払いと一致しない                                                                        | 支払いの通貨を使用                      |
| 409   | `A refund record already exists for this payment`               | この支払いには既に成功済みの返金がある                                                                 | リトライしない — GraphQL で既存返金を照会     |
| 409   | `A refund ticket already exists for this payment`               | 進行中の別チケットがブロック中                                                                     | 既存チケット終了後に再送信を検討               |
| 500   | `Internal server error`                                         | サーバ側の予期しない障害                                                                        | 指数バックオフでリトライ（5s 開始、最大 3 回）     |

<Tip>
  [GraphQL](/ja/api-reference/endpoints/graphql/orders-and-payments) を使用して作成したチケットと実行された返金レコードを照会します。返金チケットのビジネス番号で実行された返金をフィルタリングするには `refunds(filter: { refundTicketMerchantExternalId: ... })` を使用します。
</Tip>