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

# 概要

> ワンタイム決済とサブスクリプション決済の手動API統合ロードマップ。

API統合は、決済フローを完全に制御したい場合に適しています。Waffo REST APIを直接呼び出し、決済、サブスクリプション、返金、Webhook処理を自社システムに接続します。

## 適用シナリオ

* サーバー間での決済処理
* 独自のホスト型チェックアウトページや決済フォームをすでに保有している場合
* 最大限の柔軟性が求められるカスタム統合

## 統合ロードマップ

<Steps>
  <Step title="プロダクトを選択する">
    単発課金にはワンタイム決済、継続課金にはサブスクリプション決済を選択します。
  </Step>

  <Step title="必須APIを連携する">
    ワンタイム決済ではオーダー作成、オーダー照会、決済通知が必須です。サブスクリプション決済ではサブスクリプション作成、照会、ステータス通知、決済通知が必須です。
  </Step>

  <Step title="必要な条件付きAPIを追加する">
    キャンセル、返金、返金照会、返金通知、サブスクリプション管理、サブスクリプション変更は、業務フローで必要な場合のみ追加します。
  </Step>

  <Step title="API Referenceで項目詳細を確認する">
    リクエスト項目、レスポンス項目、列挙値、署名ルールは [API Reference](/docs/api-reference/introduction) を確認してください。オフラインPDFから項目定義をコピーしないでください。
  </Step>

  <Step title="サンドボックスでテストする">
    [サンドボックスとテスト](/docs/ja/developer-docs/getting-started/sandbox) を使用します。Apple Pay または Google Pay が必要な場合は、追加チェックも完了してください。
  </Step>

  <Step title="受け入れ資料を提出する">
    <a href="/docs/files/developer-docs/acceptance/one-time-payment-acceptance-cases.json" data-waffo-download-file="one-time-payment-acceptance-cases.xlsx">ワンタイム決済受け入れテンプレート</a> または <a href="/docs/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">サブスクリプション受け入れテンプレート</a> をダウンロードして実行済みケースを記入し、Waffo の技術連携グループへ提出します。
  </Step>
</Steps>

## ベースURL

| 環境      | URL                             |
| ------- | ------------------------------- |
| サンドボックス | `https://api-sandbox.waffo.com` |
| 本番      | `https://api.waffo.com`         |

## リクエスト形式

* Content-Type: `application/json`(UTF-8エンコーディング)
* すべてのリクエストはHTTP POSTを使用
* リクエストヘッダーに `X-API-KEY` と `X-SIGNATURE` を必ず含める
* すべての `/api/v1/subscription/create` リクエストで `subscriptionManagementUrl` が必須です

## レスポンス形式

```json theme={null}
{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}
```

* `code` が `"0"` の場合は成功を示します
* 失敗時は `code` がエラーコード(例: `"A0003"`)となり、`data` は空になります
* レスポンスヘッダーの `X-SIGNATURE` にはWaffoの署名が含まれており、**必ず検証してください**

## 主要API

### ワンタイム決済

| API                                                   | 必須   | 説明                                              |
| ----------------------------------------------------- | ---- | ----------------------------------------------- |
| `POST /api/v1/order/create`                           | 必須   | ワンタイム決済オーダーを作成                                  |
| `POST /api/v1/order/inquiry`                          | 必須   | リダイレクト喪失、タイムアウト、Unknown Status の復旧を含めてオーダー状態を照会 |
| Payment order notification                            | 必須   | 決済の終端結果を受信し、加盟店側オーダー状態を更新                       |
| `POST /api/v1/order/cancel`                           | 条件付き | 未決済オーダーのキャンセルが必要な場合                             |
| `POST /api/v1/order/refund`                           | 条件付き | 返金が必要な場合                                        |
| `POST /api/v1/refund/inquiry` または refund notification | 条件付き | 返金処理結果を照会または受信                                  |
| `POST /api/v1/order/capture`                          | 条件付き | Auth-Capture の手動売上確定モードのみ必要                     |

### サブスクリプション決済

| API                                     | 必須   | 説明                         |
| --------------------------------------- | ---- | -------------------------- |
| `POST /api/v1/subscription/create`      | 必須   | サブスクリプションを作成               |
| `POST /api/v1/subscription/inquiry`     | 必須   | サブスクリプション状態と主要な決済情報を照会     |
| Subscription status notification        | 必須   | 有効化、キャンセル、状態変更を受信          |
| Subscription payment order notification | 必須   | 初回決済と更新決済の結果を受信            |
| `POST /api/v1/subscription/cancel`      | 条件付き | 加盟店側でサブスクリプションをキャンセルする場合   |
| `POST /api/v1/subscription/manage`      | 条件付き | ユーザー向けサブスクリプション管理URLを生成    |
| `POST /api/v1/subscription/change`      | 条件付き | プランのアップグレードまたはダウングレードに対応   |
| `POST /api/v1/order/inquiry`            | 条件付き | サブスクリプション決済オーダーの詳細な失敗理由を照会 |

### 設定照会

| API                                    | 必須 | 説明                |
| -------------------------------------- | -- | ----------------- |
| `POST /api/v1/merchantconfig/inquiry`  | 推奨 | 加盟店の利用上限と設定を照会    |
| `POST /api/v1/paymethodconfig/inquiry` | 推奨 | 利用可能な決済手段と決済制限を照会 |

## 受け入れテンプレート

API統合とサンドボックステストの完了後、該当するテンプレートをダウンロードして記入してください：

* <a href="/docs/files/developer-docs/acceptance/one-time-payment-acceptance-cases.json" data-waffo-download-file="one-time-payment-acceptance-cases.xlsx">ワンタイム決済受け入れテンプレート</a>
* <a href="/docs/files/developer-docs/acceptance/subscription-acceptance-cases.json" data-waffo-download-file="subscription-acceptance-cases.xlsx">サブスクリプション受け入れテンプレート</a>

記入済みの受け入れ結果を Waffo の技術連携グループへ提出してください。本番移行前に [統合受け入れ基準](/docs/ja/developer-docs/tools-and-references/references/acceptance-criteria) を確認してください。