> ## 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 がどのように再試行するか、いつ再試行をやめ、それがサブスクリプションに何をもたらすか、ローリングの再試行ウィンドウの仕組み、そしてサブスクリプションに紐付く決済手段の登録・並び順・変更・削除のルール全体を説明します。

このページは、サブスクリプションの引き落としが失敗した**後**に何が起こるか、そしてサブスクリプションに紐付く決済手段について深く掘り下げます。サブスクリプション API の形と購読すべき通知については[サブスクリプション FAQ](/docs/ja/support/subscription-faq)から始めてください。開始の繰り延べや金額の更新については[サブスクリプションのライフサイクル](/docs/ja/support/subscription-lifecycle-management)を参照してください。

## サブスクリプションの引き落としが失敗しました。Waffo は自動で再試行しますか？

はい。サブスクリプションの再試行を貴社が自ら起動する必要はまったくなく、同じ期間に対して代替の注文を作成すべきでもありません。

* その期間の注文は*再試行が必要*な状態になり、Waffo は貴社の契約の再試行戦略から導かれるスケジュールで再度試行します。
* 失敗理由と試行回数を含め、すべての試行がサブスクリプション決済注文の通知で配信されるため、ポーリングせずに一連の流れを追えます。
* 再試行が進行中でも、**サブスクリプション自体は動き続けます**。ある期間が失敗してもステータスは変わりません。

## 再試行のスケジュールはどう決まりますか？

貴社の収単契約上の再試行戦略によって決まり、戦略は単一のグローバル設定ではなく**課金サイクルごとに**選択されます。Waffo はサブスクリプションの `periodType` と `periodInterval` から、6 つのバケットのいずれかに戦略を解決します。マッピングはサイクルの**長さ**によって行われ、バケットの境界は名前から想像される位置にはありません。

| `periodType` | `periodInterval` | 戦略のバケット |
| - | - | - |
| `MONTHLY` | 1–3 | `MONTHLY` |
| `MONTHLY` | 4–11 | `QUARTERLY` |
| `MONTHLY` | 12 以上 | `YEARLY` |
| `WEEKLY` | 1–3 | `WEEKLY` |
| `WEEKLY` | 4 | `MONTHLY` |
| `DAILY` | 1–6 | `DAILY` |
| `DAILY` | 7–29 | `WEEKLY` |
| `DAILY` | 30–119 | `MONTHLY` |
| `DAILY` | 120–364 | `QUARTERLY` |
| `DAILY` | 365 | `YEARLY` |
| 任意 | 間隔が保存されていない | `DEFAULT` |

驚かれやすい 2 つの帰結：**四半期**のサブスクリプション（`MONTHLY` + `3`）は `QUARTERLY` ではなく **`MONTHLY`** のバケットを使います。そして **半年**のもの（`MONTHLY` + `6`）が `QUARTERLY` に入ります。`DEFAULT` は、解決されたバケットに対して貴社の契約に戦略が設定されていない場合にも使われます。

各バケットは 3 つのつまみを持ちます。**再試行の間隔**、**間隔の単位**（日）、そしてその期間についての**最大試行回数**です。これらの値はプラットフォームの定数ではなく商業上の条件です。貴社アカウントに設定されているポリシーは Waffo の担当者にお尋ねください。また、想定したスケジュールを照合ロジックにハードコードしないでください。

## 期間ごとの最大回数に加えて、再試行全体の上限はありますか？

はい。貴社の契約の期間ごとの最大回数とは独立に、カードの再試行はアカウント全体の**ローリングウィンドウ**によって制限されます。これは Waffo が再試行頻度に関するカードスキームのルールの範囲内に留まるためです。

* ウィンドウは暦ベースではなくローリングです。暦月ではなく常に直近の期間を見ます。
* 試行がウィンドウを超えてしまう場合、その試行は失敗にはならず、**収まる最初の日付へ繰り延べられます**。
* Waffo は数値の上限を公開していません。これは Waffo のプロダクト上の判断ではなく、カードスキームの要件に追従するものだからです。契約の間隔から予測されるより後に再試行が行われ得る理由として捉えてください。

**バックアップ**の決済手段で行われた試行は、このウィンドウから意図的に除外されています（下記参照）。したがって、即時のバックアップ試行がデフォルトの決済手段の枠を消費することはありません。

## Waffo はいつ再試行をやめますか？サブスクリプションはどうなりますか？

次のいずれかが成り立つと再試行は終了します。

| 条件 | 効果 |
| - | - |
| その期間の試行が契約上の最大回数に達した | その期間の注文が**クローズ**されます。 |
| サブスクリプションがキャンセルされ、契約がキャンセル時に保留中の再試行をクローズする設定になっている | 保留中の再試行注文がクローズされます。 |

重要な点であり、最もよく混乱を招く部分：

再試行が尽きたとき、**クローズされるのはその課金期間の注文だけです。サブスクリプション自体のステータスはそのまま**で、キャンセルや一時停止の状態に移ることはなく、次の期間は予定どおり試行されます。

したがって、クローズされた期間の注文は、顧客のアクセス権を恒久的に取り消すシグナルではありません。督促の挙動（N 期間失敗したら権利を停止し、M 期間で解約するなど）が必要な場合は、期間単位の通知をもとに貴社側で実装し、ポリシーに従って自らキャンセル API を呼び出す必要があります。

## 特定の失敗が再試行可能かどうかを API のレスポンスから判断できますか？

専用のフラグからは判断できません。現在のリリースでは、サブスクリプションの失敗レスポンス、非同期通知、照会レスポンスのいずれにも**加盟店向けの「再試行可能」フィールドはありません**。次のものから状況を判断してください。

* 期間の注文のステータス（再試行中か、クローズ済みか）
* その試行に対して返された失敗コード
* 通知に含まれる試行回数を、貴社の契約の戦略と突き合わせたもの

`retryPayment` や `retryAble` のフィールドを前提にロジックを組まないでください。これらは加盟店との契約の一部ではなく、貴社向けに値が入ることもありません。

## 再試行が保留中のままサブスクリプションをキャンセルしました。その再試行は止まりますか？

契約上の 1 つの設定によります。また、その範囲は「すべてが止まる」よりも狭いものです。

* **次の再試行を待っている注文**はキャンセル時にクローズされます。ただし、契約で*キャンセル時に再試行をクローズする*設定が有効になっている場合に限ります。この設定は**既定ではオフ**なので、キャンセル後に一切の試行が行われないことが要件であれば、Waffo の担当者に確認してください。
* **すでに決済手段へ送信された注文**が、キャンセルによって強制的にクローズされることはありません。資金がすでに動いている可能性があるため、Waffo は結果を待ち続け、実際の結果を報告します。キャンセル済みのサブスクリプションでも、最後に 1 件の成功または失敗の通知が発生し得ると想定してください。
* すでに最終状態にあった注文は影響を受けません。

実務上の帰結：キャンセルを呼び出した後も、そのサブスクリプションについてもう 1 件の決済結果を受け取れる状態に Webhook ハンドラーを保っておいてください。

## 1 つのサブスクリプションに複数の決済手段を持てますか？

はい。サブスクリプションは順序付きのリストを持ちます。1 つの**デフォルト**の決済手段と、優先順位を持つ任意の数の**バックアップ**です。ユーザーはホスト型のサブスクリプション管理ページで自らリストを管理します。サブスクリプション詳細のレスポンスは `canChangePaymentMethod` と登録済みのリストを返すため、貴社独自のビューを描画できます。

登録された各決済手段には独自のステータスがあります。

| ステータス | 意味 |
| - | - |
| `IN_PROGRESS` | 追加済みで、オーソリが未完了。課金できません。 |
| `ACTIVE` | 検証済みで課金可能。**引き落としに使える唯一のステータスです。** |
| `EXPIRED` | カードの有効期限を過ぎています。課金時ではなく日次のチェックで設定されます。 |
| `SUSPENDED` | チェックアウトで提示されず、デフォルトにもできません。 |
| `CLOSED` | 最終状態。オーソリが完了しなかった決済手段を含みます。 |

## 決済手段を追加するとゼロ金額の注文が作成されるのはなぜですか？

Waffo が課金する前に、その決済手段が課金可能であることを証明する必要があるからです。ユーザーが決済手段を追加すると：

1. Waffo はその決済手段を検証するための**ゼロ金額のオーソリ注文**を作成します。
2. レスポンスは、ユーザーがオーソリを完了するための**チェックアウトリンク**を返します。リンクはキャッシュされるため、同じ決済手段で追加を再試行しても、2 回目の試行が開かれるのではなく同じリンクが返ります。
3. 決済手段は `IN_PROGRESS` として保存され、デフォルトには**なりません**。
4. オーソリに成功すると `ACTIVE` に変わります。その後に資格情報を解決できない場合は、代わりに `CLOSED` になります。保留のまま静かに残ることはありません。

検証用の注文は短命なので、リンクを保存して後で使うのではなく、速やかにユーザーを誘導してください。

## デフォルトの決済手段で課金に失敗するとどうなりますか？

バックアップが登録されている場合、Waffo は**再試行の間隔を待たずに、優先順位の順で即座に**バックアップを試します。それがバックアップの意義そのものです。数日にわたる再試行サイクルを、同じ瞬間の 2 回目の試行に変えます。

* バックアップ試行の次回再試行時刻は*現在*に設定されます。
* バックアップの試行はローリングウィンドウに**加算されない**ため、デフォルトの決済手段の枠を消費しません。
* バックアップの試行は、ユーザーへの再試行終了のメールを**発生させません**。
* すべてのバックアップを試して失敗すると、デフォルトの決済手段が戻され、通常の間隔ベースの戦略が再開します。

## どの決済手段の変更がブロックされますか？

| 試み | 結果 |
| - | - |
| `ACTIVE` でないサブスクリプションの決済手段を変更する | 拒否されます。キャンセル済みと期限切れのサブスクリプションを含み、その他すべての非アクティブなステータスも同様です。 |
| まだ開始していないサブスクリプションで、最初の登録前に決済手段を変更する | 許可されます。これが上記のルールの唯一の例外です。 |
| `ACTIVE` なサブスクリプションの**デフォルト**の決済手段を削除する | 拒否されます。先に別のデフォルトを設定してから削除してください。 |
| `ACTIVE` でない決済手段を削除する、またはデフォルトに設定する | 拒否されます。有効な対象は `ACTIVE` の決済手段のみです。 |

## ユーザーのカードがもうすぐ期限切れです。Waffo は警告しますか？カードを更新しますか？

どちらも前提にすべきではありません。ここは最もよくある誤解なので、注意して読んでください。

* **Waffo はイシュアー側のカード更新情報から保存済みカードを更新しません。** 自動のアカウントアップデーターの連携はありません。銀行が新しい番号や有効期限でカードを再発行しても、保存された資格情報が静かに追従することは**ありません**。再登録を前提に計画してください。
* Waffo は、有効期限が近づいている決済手段についてサブスクリプション詳細のレスポンスに**期限間近のフラグ**を出すため、貴社のプロダクト内でユーザーに促すことができます。メールではなくこのフラグを、行動すべきシグナルとして扱ってください。
* 有効期限が過ぎると、日次のチェックがその決済手段を `EXPIRED` に移し、課金できなくなります。
* ウォレット型の保存済み決済手段は異なります。ウォレット自身が資格情報の更新や連携解除を Waffo に通知する場合、その更新は適用されます。これは通常の保存済みカードには及びません。

恒久的な安全策は、すべてのサブスクリプションに少なくとも 1 つの**バックアップの決済手段**を登録しておくことと、期限間近のフラグが現れ次第ユーザーに促すことです。

## 購入者のカードが、課金の前にチェックアウトで拒否されました。なぜですか？

一部のカード商品は継続課金に適しておらず、貴社の契約はサブスクリプション向けに**ブロック対象のカードサブタイプ**の一覧を持ち得るためです。チェックアウト中に Waffo はカードの BIN を照会し、そのサブタイプが一覧にあればカード系の決済手段は選択肢から除外されます。何も残らない場合、購入者には次のようなメッセージが表示されます。

> Sorry, we do not accept this type of card for subscriptions. Please try a
> different card (e.g., standard Credit or Debit card).

対処にあたっての注意：

* 一覧は契約ごとに設定されます。プラットフォーム全体で固定のブロックリストはないため、貴社アカウントに何が設定されているかは Waffo の担当者にお尋ねください。
* チェックは、サブスクリプションを作成するときではなく、購入者が実際に入力したカードに対して**チェックアウト時**に行われます。したがって、サブスクリプションの作成が成功しても、購入者がチェックアウトページで断られることがあります。
* 復旧の経路は他の決済拒否と同じです。購入者に別のカードを依頼してください。同じカードで再試行しても結果は変わりません。

## `numberOfPeriod` を渡しませんでした。サブスクリプションはいつ終了しますか？

`numberOfPeriod` の省略は実質的な「無期限」を意味しません。貴社の契約はサブスクリプションの**最大継続年数**を持ち、Waffo はそこから総期間数を解決します。

* `numberOfPeriod` を省略した場合、総期間数と終了時刻は開始時刻に契約の最大継続期間を加えて**導出されます**。作成リクエストは受理され、何も拒否されません。導出された値は最初の期間が成功した時点で書き込まれるため、自分で計算するのではなくサブスクリプションから読み戻してください。
* `numberOfPeriod` を指定したが、最後の引き落としがその最大継続期間を超えてしまうほど長い場合、作成は切り詰められるのではなく**拒否されます**。同じチェックは `numberOfTrialPeriod` にも適用されます。返るのは「利用可能な決済手段がない」エラーですが、このケースでは「このカードはサポートされていない」ではなく「これほど長いサブスクリプションを担える契約がない」という意味です。

カードの有効期限は、どちらの計算の入力にも**なりません**。来年期限切れになるカードがサブスクリプションを短くすることはなく、単にその決済手段が `EXPIRED` に移り、新しいものを登録する必要が生じるだけです。


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