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

# サブスクリプションのライフサイクルと決済手段の管理

> 将来の日付に開始するサブスクリプションの予約方法、開始前にできること、ユーザーが複数の決済手段を管理しバックアップでの自動リトライを受ける仕組み、金額更新のルール、Waffo がエンドユーザーに送信するライフサイクル通知。

サブスクリプションのライフサイクルにおける開始日の繰り延べ、決済手段の管理、エンドユーザー通知について説明します。
アップグレード、期間ごとの金額、Webhook の選択は
[サブスクリプション FAQ](/docs/ja/support/subscription-faq) で扱っています。

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

はい。`/api/v1/subscription/create` を呼び出す際に `startTime`（タイムゾーン付き ISO 8601）を渡します。

* サブスクリプションは即時に作成され、`startTime` が到来すると自動的に有効化されます。貴社側でスケジューラーは
  不要です。開始日より前でもステータスはすでに `ACTIVE` で、請求期間はまだ消費されていません。そのため、
  まだ開始していないサブスクリプションと稼働中のものを区別するには、ステータスではなく `startTime` を読み取ってください。
* トライアルが設定されている場合、トライアルは `startTime` から数え始めます。設定されていない場合、初回の引き落としは
  `startTime` に実行されます。
* `startTime` は厳密に将来であり、最大 365 日先までである必要があります。省略すると現在の動作（即時開始）が維持されます。
* 有効化時に Waffo は有効化の Webhook をプッシュします。初回引き落としの失敗は通常のリトライフローに入ります。

## 開始日より前にユーザーの決済手段は検証されますか？

はい。作成時に、決済手段を検証して将来の請求用にトークンを保存する**金額ゼロのオーソリ**を行います。
ユーザーには決済ではなく「検証のみ、本日の請求なし」のステップが表示されます。

* 検証に失敗した場合、サブスクリプションは**作成されず**、API は決済手段検証エラーを返します。ユーザーに別の
  決済手段を試すよう案内してください。
* このフローには、貴社の契約で金額ゼロの注文が許可されている必要があります。許可されていない場合、作成は拒否されます。
* 資金が保留されることはないため、開始日より前のキャンセルに返金処理は不要です。

## 開始日より前に許可される操作は何ですか？

| 操作 | 可否 | 動作 |
| - | - | - |
| キャンセル | 可 | ステータスは `MERCHANT_CANCELLED`（ホスト型ページからの場合は `USER_CANCELLED`）になり、引き落としは一切発生しません。 |
| 金額の更新（`amount` / `scheduledAmounts`） | 可 | 新しい値はサブスクリプションの有効化後に適用されます。 |
| プラン変更（アップグレード / ダウングレード） | 不可 | サブスクリプションが開始していない間は拒否されます。代わりにキャンセルして再作成してください。 |
| 照会 | 可 | `startTime` を含むサブスクリプションを返します。請求期間はまだ消費されていません。 |

## ユーザーは既存のサブスクリプションの決済手段を変更・追加できますか？

はい。ホスト型のサブスクリプション管理ページで行えます。ユーザーは決済手段の追加、新しいデフォルトの設定、
バックアップの並べ替え、決済手段の削除ができます。

* **カード、Apple Pay、Google Pay** のサブスクリプションのみサポートされ、キャンセル済みまたは期限切れの
  サブスクリプションでは利用できません。有効なサブスクリプションのデフォルトの決済手段は削除できません。
* サブスクリプション詳細のレスポンスには `canChangePaymentMethod` と紐づいた決済手段の一覧が返されるため、
  貴社独自の UI を構築できます。
* 新しく追加された決済手段は同じ金額ゼロのオーソリフローで検証されます。デフォルトの切り替えは次回の引き落としから
  有効になります。

## デフォルトの決済手段で請求に失敗した場合はどうなりますか？

バックアップの決済手段が紐づいている場合、Waffo は通常のリトライ間隔を待たずに、**優先順位に従ってバックアップで
即時にリトライ**します。

* バックアップが成功すると、ユーザーにメールが送られ、それを新しいデフォルトにするかどうかを尋ねられます
  （ユーザーが確認するまで、保存されたデフォルトは変更されません）。
* すべてのバックアップが失敗した場合、注文はデフォルトの決済手段に対する設定済みのリトライ戦略にフォールバックします。
  バックアップの試行はカードスキームのローリングリトライ枠にカウントされ**ず**、決済失敗メールも発生させません。
  [サブスクリプションのリトライと決済手段](/docs/ja/support/subscription-retry-and-payment-methods-faq)を参照してください。

## 更新 API で金額を引き上げることはできますか？

いいえ。`/api/v1/subscription/update`（`amount` と `scheduledAmounts` の両方）は、現在の値**以下**の値のみを
受け付けます。より高い金額を請求するには `/api/v1/subscription/change` を使い、ユーザーを新しいプランに移行してください。

更新が成功すると、Waffo は加入者に価格変更通知（元の金額、新しい金額、適用期間）をメールで送信し（貴社のアカウントで
その通知が有効になっている場合）、サブスクリプションの `notifyUrl` に `SUBSCRIPTION_UPDATE_NOTIFICATION` を
プッシュします。`update` のレスポンスは依然として変更内容の主たる記録なので、保存してください。Webhook は同じ変更を
非同期で確認するものです。変更は次の請求期間から適用され、現在の期間には影響しません。
[サブスクリプションの金額と期間ごとのスケジューリング](/docs/ja/support/subscription-amount-scheduling-faq)を参照してください。

## Waffo はエンドユーザーにどの通知を送信しますか？

Waffo はライフサイクルの重要な時点で加入者に直接メールを送信します。各タイプはマーチャントごとに有効・無効を
設定できます。言語は、設定されていればサブスクリプションの `cashierLanguage`、そうでなければユーザー通貨から導出されます。

| 通知 | トリガー |
| - | - |
| サブスクリプション有効化 | 初回期間の決済が成功。 |
| トライアル終了リマインダー | トライアル期間の終了直前に送信。 |
| 請求予定の通知 | トライアル期間を含め、各引き落としの前に送信。 |
| 決済失敗 | スケジュールされたリトライまたは最終試行が失敗。ユーザーが決済手段を追加・更新するためのリンクを含む。初回期間の失敗およびバックアップ手段での試行では送信**されません**。 |
| キャンセル確認 | キャンセルが完了。 |
| サブスクリプション変更 | 貴社が更新 API で金額を変更。 |

正確なタイミング、抑制ルール、二重送信を避ける方法は
[顧客へのサブスクリプションメール](/docs/ja/support/subscription-notifications-faq)にあります。

## 失敗した引き落としはどのようにリトライされますか？

貴社の契約で設定されたリトライ戦略に従って自動的にリトライされます。スケジュールは請求サイクルに合わせて調整されます。
追加の動作：

* リトライは、その期間の試行回数が契約上の上限に達したとき（その期間の注文はクローズされますが、サブスクリプション自体は
  `ACTIVE` のまま）、またはキャンセル時リトライ終了の設定がオンの状態でサブスクリプションがキャンセルされたときに終了します。
  リトライを早期に終了させる「リトライ不可の拒否」という独立した分類は存在しません。
* カードのリトライはさらにカードネットワークのコンプライアンスルールによって上限が設けられ、上限を超える試行は
  自動的に延期されます。
* サブスクリプションがキャンセルされた瞬間に保留中のリトライが停止するかどうかは、貴社の契約の設定によります。
  キャンセル後に一切の試行が行われないことを要件とする場合は、連携サポートにこの設定を確認してください。


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