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

# サブスクリプションの作成・検証 FAQ

> サブスクリプション作成時に Waffo が受け付ける正確な値の範囲、同時に指定が必要なフィールド、サブスクリプションステータスの全一覧と有効な遷移、および作成リトライ、照会、将来の開始日の動作について説明します。

サブスクリプションが存在する**前**に正しくなければならないすべての事項：受け付けられる値の範囲、同時に指定が必要なフィールド、そして作成レスポンスの意味です。

金額の設定については
[サブスクリプションの金額と期間ごとのスケジューリング FAQ](/docs/ja/support/subscription-amount-scheduling-faq)
をご覧ください。通貨をまたぐ動作と Portal での検索については
[通貨をまたぐサブスクリプションと Portal FAQ](/docs/ja/support/subscription-cross-currency-and-portal-faq)
をご覧ください。

## どのような課金サイクルを設定できますか？

`periodType` と `periodInterval` の組み合わせでサイクルの長さが定義されます。どちらも必須で、受け付けられる `periodInterval` の範囲は `periodType` によって異なります：

| `periodType` | `periodInterval` の範囲 | サイクルの長さ |
| - | - | - |
| `DAILY` | 1–365 | N 日ごと |
| `WEEKLY` | 1–4 | N 週ごと |
| `MONTHLY` | 1 以上 | N か月ごと |

**`YEARLY` という期間タイプはありません。** 年間サブスクリプションには、`periodType: MONTHLY` と `periodInterval: 12` を使用してください。

加盟店からよく名前で尋ねられるサイクルも、この 2 つのフィールドで対応できます：

| 希望するサイクル | 設定 |
| - | - |
| 週次 | `WEEKLY` + `1` |
| 2 週ごと | `WEEKLY` + `2` |
| 月次 | `MONTHLY` + `1` |
| 四半期ごと | `MONTHLY` + `3` |
| 半年ごと | `MONTHLY` + `6` |
| 年次 | `MONTHLY` + `12` |

個々の決済手段によってはさらに制限が狭まる場合があります。日次サイクルを拒否するものや、特定のサイクル/間隔の組み合わせしか受け付けないものもあります。上記の範囲を満たすサイクルでも、選択した決済手段によっては拒否されることがあります。

## トライアル期間に通常期間と異なるサイクルを使用できますか？

はい。トライアルのサイクルは、`trialPeriodType` と `trialPeriodInterval` によって通常のサイクルとは独立して設定され、受け付けられる範囲は通常期間と同じです：

| `trialPeriodType` | `trialPeriodInterval` の範囲 |
| - | - |
| `DAILY` | 1–365 |
| `WEEKLY` | 1–4 |
| `MONTHLY` | 1 以上 |

* `trialPeriodType` と `trialPeriodInterval` は**同時に**指定する必要があります。片方だけの指定は拒否されます。
* 両方を省略した場合、トライアルは `periodType` と `periodInterval` をそのまま再利用します。
* 独立して設定できるからといって、相互チェックが**ない**わけではありません。次の質問をご覧ください。

## 同時に指定しなければならないサブスクリプションのフィールドはどれですか？

| グループ | ルール |
| - | - |
| `trialPeriodType` + `trialPeriodInterval` | 両方指定するか、両方省略する |
| `trialPeriodAmount` + `numberOfTrialPeriod` | 両方指定するか、両方省略する。このペアは、トライアルサイクルを設定する場合だけでなく、トライアルを設定するすべての場合に必須です |
| `amount` | 作成時に常に必須 |

また、トライアルサイクルは独立して設定されるものの、以下のフィールド間ルールが適用されます：

| ルール | 違反時の動作 |
| - | - |
| `numberOfTrialPeriod` は `numberOfPeriod` `≤` でなければならない（`numberOfPeriod` が存在する場合のみチェック） | 拒否 |
| `trialPeriodAmount` は `amount` より**厳密に小さく**なければならない（`0` は許可、同額は不可） | 拒否 — `trial period amount should be less than subscription amount` |
| `trialPeriodAmount` は通貨の小数桁数に一致しなければならない | 拒否 — 金額小数桁エラー |
| 決済手段がスケジュールを決定する決済手段の場合、トライアルサイクルは通常サイクルと**同一**でなければならない | 拒否 |

## サブスクリプションは何期間まで継続できますか？

| `numberOfPeriod` | 意味 |
| - | - |
| 指定あり | **1 より大きい**必要があります。サブスクリプションはその期間数の後に終了します。 |
| 省略 / 空 | 加盟店が定義した終了はありません。 |

「加盟店が定義した終了はない」といっても、文字どおり無制限ではありません。`numberOfPeriod` のないサブスクリプションも、サブスクリプション契約の最大期間によって制限されており、Waffo はその期間と貴社のサイクルから実効的な最終期間数を導出します。決済手段によっては、独自の最大期間を課すものもあります。そのため、終了を設定していなくても、いずれ最終期間に達することを前提に設計してください。

サブスクリプションが最終期間に達すると、金額の更新は拒否されます。[金額ページ](/docs/ja/support/subscription-amount-scheduling-faq)をご覧ください。

## サブスクリプション作成時に `goodsUrl` と `appName` は必須ですか？

**いいえ。** `/api/v1/subscription/create` ではどちらもオプションであり、両方なしでもサブスクリプションを作成できます。

ご覧になったことがあるかもしれない「`goodsUrl` または `appName` のいずれかを指定する」というルールは、サブスクリプション作成ではなく、**ワンタイム注文の作成**に属するものです。個々の契約ではコンプライアンスやリスク上の理由から `goodsUrl` を必須とする場合があるため、いずれか一方を指定することは引き続き良い慣行です。ただし、これはサブスクリプション作成の一律の検証ではなく、そうであるかのように連携を構築すると、拒否をデバッグする際に誤った方向へ導かれます。

## サブスクリプションのステータスにはどのようなものがあり、どの遷移が有効ですか？

9 つのステータスが存在します。各ステータスには到達可能な特定の元ステータスが定められているため、予期しないステータスが表示された場合、通常は無効な状態の兆候ではなく、以前の遷移を見逃した兆候です：

| ステータス | 意味 | 有効な元ステータス |
| - | - | - |
| `IN_PROGRESS` | ユーザーがサブスクリプションの確認を完了していない | —（作成時のみ。遷移によって到達することはない） |
| `AUTHORIZATION_REQUIRED` | 決済手段がユーザーの認可を必要としている | `IN_PROGRESS` |
| `ACTIVE` | 稼働中 | `AUTHORIZATION_REQUIRED`、`IN_PROGRESS` |
| `CLOSE` | 有効化前にタイムアウトまたは失敗したためクローズ | `ACTIVE`、`AUTHORIZATION_REQUIRED`、`IN_PROGRESS` |
| `MERCHANT_CANCELLED` | 貴社がキャンセル | `ACTIVE` |
| `USER_CANCELLED` | エンドユーザーがキャンセル | `ACTIVE` |
| `CHANNEL_CANCELLED` | 決済手段側でキャンセル（例：ユーザーがウォレットで認可を取り消した） | `ACTIVE`、`AUTHORIZATION_REQUIRED`、`IN_PROGRESS` |
| `PLATFORM_CANCELLED` | いずれかの課金で異議申し立て、チャージバック、または不正シグナルが発生したため、Waffo が自動的にキャンセル | `ACTIVE` |
| `EXPIRED` | 最終期間に到達 | `ACTIVE` |

貴社の連携で必要になると思われる形でグループ化すると：

| グループ | ステータス |
| - | - |
| 未有効化 | `IN_PROGRESS`、`AUTHORIZATION_REQUIRED` |
| 稼働中 | `ACTIVE` |
| 終端 | `CLOSE`、`MERCHANT_CANCELLED`、`USER_CANCELLED`、`CHANNEL_CANCELLED`、`PLATFORM_CANCELLED`、`EXPIRED` |
| キャンセル（終端の部分集合） | `MERCHANT_CANCELLED`、`USER_CANCELLED`、`CHANNEL_CANCELLED`、`PLATFORM_CANCELLED` |

終端グループ全体を「今後新たな課金期間は開始されない」と扱い、個々の値ではなくグループで分岐してください。そうすれば、マッピングしていないステータスが知らないうちに有効なサブスクリプションのように見えることはありません。

## `PLATFORM_CANCELLED` とは何ですか？

そのサブスクリプションのいずれかの課金で異議申し立て、チャージバック、または不正シグナルが発生したため、Waffo が**自らの判断で**サブスクリプションをキャンセルした際に設定する終端ステータスです。他のキャンセルと同様にサブスクリプションステータス通知を通じて届き、通知にはどの種類のシグナルがトリガーとなったかを示すキャンセル理由が含まれます。

連携上重要なポイント：

* `ACTIVE` からのみ到達可能です。
* 自動キャンセルは**加盟店ごと、シグナルタイプごとに設定可能**で、設定されていない限りオフです。そのため、この値を目にすることが一度もない可能性があり、この値がないことは異議申し立てが無視されていることを意味しません。
* 貴社ではなく Waffo が開始したものであるため、通知を処理するまで貴社側の記録ではサブスクリプションが有効と表示されます。Webhook を正となる情報源として扱ってください。

異議申し立てとチャージバックの処理自体については
[チャージバック FAQ](/docs/ja/support/chargeback-faq)
をご覧ください。

## 作成時に `AUTHORIZATION_REQUIRED` が返されました。どうすればよいですか？

ユーザーはまだ継続課金の委任（マンデート）を認可する必要があります。作成レスポンスには `subscriptionAction` が含まれ、その中にユーザーを送るべき URL（`webUrl`）があります。ユーザーをそこへリダイレクトしてください。認可が成功すると、サブスクリプションは `ACTIVE` に移行します。

`subscriptionAction` は、サブスクリプションが `IN_PROGRESS` または `AUTHORIZATION_REQUIRED` の間のみ設定されます。サブスクリプションが有効または終端になると返されなくなりますが、これはエラーではなく想定どおりの動作です。

認可リンクには時間制限があります。作成リクエストの `orderExpiredAt` がその期限を設定します。省略した場合はプラットフォームのデフォルトが適用されますが、これは**短く**、数時間ではなく数分単位です。そのため、ユーザーをすぐにリンクへ送ってください。期限内に認可が完了しなかったサブスクリプションは `CLOSE` に移行します。

## 同じリクエスト ID で create を再度呼び出すとどうなりますか？

作成は、貴社が生成するリクエスト ID である **`subscriptionRequest`** に対して冪等であり、`merchantSubscriptionId` に対してではありません。同じ MID の下で同じ `subscriptionRequest` を使って再度呼び出しても、2 つ目のサブスクリプションは作成されません。

返される内容は、既存のサブスクリプションがどこまで進んでいるかによって異なります：

| 既存のステータス | 再作成時の動作 |
| - | - |
| `AUTHORIZATION_REQUIRED` | **保存済み**の認可リンクとともにサブスクリプションを返します。新しいリンクは生成されません。 |
| `IN_PROGRESS` | Waffo が保留中の支払いステップを再駆動するため、この呼び出しでは新たに発行されたリンクが返される**ことがあります**。 |
| その他のステータス | 既存のサブスクリプションを返します。リンクは含まれません。 |

再呼び出しでは整合性も検証されます。`amount` または `currency` が元のリクエストと異なる場合、黙って受け付けられるのではなく重複として拒否されます。そのため、**同一の**ペイロードでリトライし、1 つの `subscriptionRequest` を 2 つの異なるサブスクリプションで再利用しないでください。

ユーザーが認可を途中で放棄し、新しいリンクを渡す必要がある場合は、サブスクリプションがまだ有効化前の状態のうちに作成をリトライし、返ってきた `subscriptionAction` を使用してください。リンクをキャッシュして有効なままだと想定しないでください。

## サブスクリプションを照会し、期間ごとの課金を取得するにはどうすればよいですか？

`/api/v1/subscription/inquiry` を **`subscriptionRequest` または `subscriptionId`** を指定して呼び出します。少なくとも一方が必須です。両方を渡すことも受け付けられます。

期間ごとの課金はデフォルトでは返され**ません**。取得するには `paymentDetails` を `1` に設定してください（デフォルトの `0` では省略され、それ以外の値は拒否されます）：

| `paymentDetails` | レスポンス |
| - | - |
| `0`（デフォルト） | サブスクリプションのみ |
| `1` | サブスクリプションに加えて、課金期間ごとに 1 エントリの `paymentDetails` リスト |

各 `paymentDetails` エントリには `acquiringOrderId`、`orderCurrency`、`orderAmount`、`orderStatus`、`orderUpdatedAt`、`period` が含まれ、追加（シート追加）課金があった期間には `topupDetails` リストも含まれます。これらの行の番号付けについては
[通貨をまたぐサブスクリプションと Portal FAQ](/docs/ja/support/subscription-cross-currency-and-portal-faq)
をご覧ください。

逆方向、つまり課金からそのサブスクリプションを辿る場合、注文照会レスポンスには `subscriptionId`、`period`、`subscriptionRequest`、およびその課金が期間課金か決済手段の追加かを示す `subscriptionEvent` を含む `subscriptionInfo` ブロックが含まれます。ワンタイム注文には `subscriptionInfo` はありません。

サブスクリプションレスポンスには `productInfo.currentPeriod` と保存済みの `productInfo.scheduledAmounts` も含まれ、これは金額変更をスケジュールする前に読み取るものです。

## 1 人のユーザーは何件のサブスクリプションを持てますか？

いくつでも持てます。1 つの MID の下で、同じ `merchantUserId` は貴社が作成した数だけサブスクリプションを保持できます。ユーザーごとの上限はなく、作成時に `merchantUserId` の一意性チェックも行われません。

これは複数商品・複数シートのビジネスでは通常の形です。1 人のユーザーが複数のサブスクリプションを同時に持ち、それぞれが独自の `subscriptionId` と独自のライフサイクルを持ちます。そのため、`merchantUserId` を「そのユーザーのサブスクリプション」のキーとして扱わないでください。`subscriptionId` または貴社独自の `merchantSubscriptionId` をキーにしてください。

## サブスクリプションを将来の日付から開始できますか？

はい。作成時に `startTime` を渡してください。検証：

| ルール | 動作 |
| - | - |
| `startTime` を省略 | サブスクリプションは即時開始（従来の動作と変わらず） |
| `startTime` が厳密に将来 | 受け付け |
| `startTime` が過去、または現在と同じ | 拒否 — 無効な開始時刻 |
| `startTime` が **365 日**より先 | 拒否 — 開始時刻が遠すぎる |

**過去日付への設定（バックデート）はサポートされていません。** 以前に開始したかのように動作するサブスクリプションを作成する方法はなく、最初の期間を過去に設定する方法もありません。すでに経過した期間に対して請求する必要がある場合は、別のワンタイム注文として回収してください。

開始を先延ばしする場合のさらに 2 つの制約：

* 開始日は、使用される契約の有効期間内に収まっていなければなりません。そのため、365 日以内であっても、遠い開始日はその理由で拒否されることがあります。
* プラン変更の場合、`startTime` は元のサブスクリプションの次回予定課金より前であってはなりません。

作成から開始日までの間にできること・できないことについては
[サブスクリプションのライフサイクルと決済手段の管理](/docs/ja/support/subscription-lifecycle-management)
をご覧ください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.