> ## 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 は**返金チケット**システムを採用しています。購入者は API またはカスタマーポータルを通じて返金をリクエストし、各リクエストは定義されたライフサイクルを持つチケットとして作成されます。マーチャントはダッシュボードからチケットを審査し、解決します。

***

## ビジネスルール

<Note>
  これらのルールは API によって強制されており、上書きすることはできません。
</Note>

* **単発商品**は支払いから **14 日以内**に返金対象となります。
* **サブスクリプション**は返金チケットシステムを使用しません。キャンセルは現在の請求期間の終了時に有効になります。
* **一部返金**は、チケット作成時にカスタム `amount`（表示形式の文字列、例："15.00"）を指定することでサポートされます。

***

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

すべての返金チケットは以下のライフサイクルを経ます：

<CardGroup cols={3}>
  <Card title="pending" icon="clock" color="#f59e0b">
    返金がリクエストされ、審査待ち。
  </Card>

  <Card title="approved" icon="check" color="#22c55e">
    マーチャントにより返金が承認された。
  </Card>

  <Card title="rejected" icon="xmark" color="#ef4444">
    返金リクエストが却下された。
  </Card>

  <Card title="processing" icon="spinner" color="#8b5cf6">
    決済プロバイダーによる返金処理中。
  </Card>

  <Card title="succeeded" icon="check-double" color="#3b82f6">
    返金が正常に完了。
  </Card>

  <Card title="failed" icon="triangle-exclamation" color="#dc2626">
    返金処理が失敗。
  </Card>
</CardGroup>

***

## 返金チケットの作成

API Key 認証を使用して API を呼び出し、返金チケットを作成します。

### エンドポイント

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

**認証：** API Key

### リクエストボディ

<ParamField body="paymentId" type="string" required>
  返金対象の支払い ID（UUID v4）。
</ParamField>

<ParamField body="reason" type="string" required>
  返金をリクエストする理由の説明。
</ParamField>

<ParamField body="amount" type="string">
  表示形式の文字列での返金金額（例："15.00"）。全額返金の場合は省略します。
</ParamField>

### レスポンス

<ResponseField name="ticketId" type="string">
  作成された返金チケットの一意な ID。
</ResponseField>

<ResponseField name="status" type="string">
  チケットの初期ステータス。作成時は常に `pending`。
</ResponseField>

<ResponseField name="requestedAmount" type="string">
  表示形式の文字列での返金金額。
</ResponseField>

### 使用例

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/refund-ticket/create-ticket \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
    -d '{
      "paymentId": "550e8400-e29b-41d4-a716-446655440000",
      "reason": "Product not as described",
      "amount": "15.00"
    }'
  ```

  ```typescript SDK theme={"system"}
  import { WaffoPancake } from "@waffo/pancake-ts";

  const client = new WaffoPancake({
    merchantId: process.env.WAFFO_MERCHANT_ID!,
    privateKey: process.env.WAFFO_PRIVATE_KEY!,
  });

  const { ticketId, status, requestedAmount } = await client.refunds.createTicket({
    paymentId: "550e8400-e29b-41d4-a716-446655440000",
    reason: "Product not as described",
    amount: "15.00",
  });
  ```
</CodeGroup>

***

## 返金チケットの照会

GraphQL を使用して返金チケットデータを取得します。

```graphql theme={"system"}
query {
  refundTickets(storeId: "STORE_ID") {
    id
    paymentId
    storeId
    customerId
    reason
    status
    requestedAmount
    approvedAmount
    currency
    createdAt
    updatedAt
    resolvedAt
  }
}
```

| フィールド             | 型      | 説明                             |
| ----------------- | ------ | ------------------------------ |
| `id`              | string | 返金チケット ID                      |
| `paymentId`       | string | 関連する支払い ID                     |
| `storeId`         | string | 支払いが属するストア                     |
| `customerId`      | string | 返金をリクエストした購入者                  |
| `reason`          | string | 購入者が提供した理由                     |
| `status`          | string | 現在のチケットステータス                   |
| `requestedAmount` | string | 購入者がリクエストした金額（表示形式の文字列）        |
| `approvedAmount`  | string | 承認された金額（リクエスト金額と異なる場合あり）       |
| `currency`        | string | ISO 4217 通貨コード                 |
| `createdAt`       | string | ISO 8601 タイムスタンプ               |
| `updatedAt`       | string | ISO 8601 タイムスタンプ               |
| `resolvedAt`      | string | ISO 8601 タイムスタンプ（未解決の場合は null） |

***

## Webhook 通知

返金チケットイベントが発生した際に通知を受信するよう Webhook を設定できます。設定手順は [Webhooks ガイド](/ja/integrate/webhooks)をご覧ください。

***

## 返金リクエストの削減

<AccordionGroup>
  <Accordion title="明確な商品説明">
    正確な説明により「期待と異なる」という返金リクエストを減らせます。
  </Accordion>

  <Accordion title="トライアル期間">
    購入前に試用してもらうことで、購入後の後悔を減らせます。
  </Accordion>

  <Accordion title="迅速なサポート対応">
    問題を迅速に解決し、返金リクエストに発展する前に対応します。
  </Accordion>

  <Accordion title="認識しやすい請求明細">
    顧客が課金を認識できる明確な請求明細を使用します。
  </Accordion>
</AccordionGroup>