更新の課金は実際にいつ開始されますか？
Waffo はサブスクリプションに次回課金タイムスタンプを保存し、そのタイムスタンプを過ぎた後の定期スイープでその期間の課金を開始します。ここから 2 つのことが導かれます。- 日付は確定的ですが、時刻は確定的ではありません。照合とユーザーへの案内は、分単位ではなく日単位で計画してください。
- 保存されているサブスクリプションのすべてのタイムスタンプ — 次回課金時刻、期間の開始と終了、サブスクリプションの終了時刻 — は UTC で、API は ISO 8601 形式で返します。請求カレンダーが現地時間の場合は、お客様側で変換してください。加盟店ごとの請求タイムゾーン設定はありません。
/api/v1/subscription/create の startTime で、これがスケジュール全体の基準となるアンカーを設定します — サブスクリプションの作成と検証を参照してください。
2 回目以降の請求日はどのように導出されますか？
サブスクリプションの開始時刻に、サイクルを丸ごと加算して求めます。31 日に開始した月次サブスクリプションは、2 月にはどうなりますか？
短い月ではその月の最終有効日に丸められ、その後は 31 日に戻ります。 すべての期間は開始 + n か月として計算されるため、1 月 31 日に 1 か月を加えると 2 月 28 日（閏年は 29 日）になります — 2 月 31 日は存在しません — が、2 か月を加えると 3 月 31 日、3 か月を加えると 4 月 30 日になります。丸めは着地する月にのみ適用され、新しいアンカーにはなりません。
これは月末サブスクリプションで最も多く見られる想定外の動作です：サブスクリプションは確かに 31 日に戻ります。 31 日に開始したユーザーは毎月の最終日 — その月にある 28 日、29 日、30 日、31 日のいずれか — に課金されます。このようなサブスクリプションに対して、固定の日付を前提としたリマインダーを構築しないでください。
安定した日付での請求が商品にとって重要な場合は、すべての月に存在する日（1〜28 日）にサブスクリプションを開始するか、「今」にアンカーを決めさせるのではなく
startTime を明示的に設定してください。
ある期間が 3 日間の再試行の後にようやく成功しました。次の期間は動きますか？
デフォルトでは動きません。 次の期間は上記のとおりサブスクリプションの開始から計算されるため、再試行で回復した期間が以降のスケジュールを後ろにずらすことはありません — ユーザーが日数を得ることはありません。 代わりにスケジュールを実際の支払い時刻に再基準化するアカウントレベルの設定があります。有効化されている場合、更新が成功するとその課金が成功した時点から次回課金日が再計算され、サブスクリプションの終了日もあわせて再計算されます。これについて知っておくべきことは 2 点です。- スケジュールを動かすのは前方のみです。再計算された日付が保存されている日付より早い場合は、保存されている日付が維持されます。
- これは Portal ではなく、Waffo が収単契約上で設定します。「ユーザーは実際に支払った日から常にフルサイクルを得る」という動作が必要な場合は、どちらかを前提に構築する前に、お客様のアカウントにどの動作が設定されているかを Waffo の担当者に確認してください。
/api/v1/subscription/inquiry から nextPaymentDateTime を読み取ってください。
「次回課金」のリマインダーにはどの日付フィールドを読むべきですか？
つまり、リマインダーには
nextPaymentDateTime を読んでください。ただし、ユーザーに日付を約束する前に 2 つのケースを処理してください。
nullは「これ以上課金がない」という意味ではありません。 Waffo はサブスクリプションの更新が保留されている間 — 例えば現在の期間がまだ試行中である、またはプラン変更がその期間に対して保留中であるなど —nullを返します。保留が解除されると日付は再び表示されます。nullは完了ではなくまだ不明として扱ってください。- 最終期間では、値は将来ではなく古いものです。 そこでは進まないため、最終期間自身の日付が引き続き表示されます。ユーザーに再度課金されると伝える前に、
currentPeriodをサブスクリプションの最終期間数と照合するか、endDateTimeを確認してください。
期間ごとの課金ステータスは何を意味しますか？
各請求期間には独自の注文があり、独自のステータスを持ちます。Portal ではこれらを Initial、To Pay、Retrying、Paid、Closed と表示します。
ラベルより重要な 2 つのルールがあります。
PAY_SUCCESSとORDER_CLOSEが唯一の最終ステータスです。それ以外はまだ変わる可能性があります。- 期間が
ORDER_CLOSEに達しても、サブスクリプション自体のステータスは変わりません。サブスクリプションはACTIVEのままで、次の期間は予定どおり試行されます。権利付与の判断は、これらの期間ごとの結果からお客様が行うものです。サブスクリプションの再試行と決済手段を参照してください。
最初の課金がまったく再試行されなかったのはなぜですか？
即時開始のサブスクリプションの初回課金は、バックグラウンドの更新ではなくユーザー在席型の決済だからです。失敗した場合、その期間の注文は直ちにクローズされます。再試行スケジュールも、バックアップ決済手段の試行も、ユーザーへの決済失敗メールもありません。 その理由は、ユーザーがまさにその場にいるからです — 正しい回復方法は、ユーザーに再度試してもらうか別の決済手段を試してもらうことであり、ユーザーが失敗を見ているカードを再試行することではありません。
2 行目が、人がつまずく例外です。開始が遅延されたサブスクリプションは事前に認可され、後でユーザー不在のまま課金されるため、その初回課金は以降のすべての課金と同じように動作します。
即時開始のケースの回復方法は、ユーザーが別の決済手段を選んだ後に新しいサブスクリプションを作成することです。同じ期間に対して別のワンタイム注文を作成し、サブスクリプションがそれを認識することを期待しないでください。
待つのではなく、失敗した期間をユーザー自身に支払わせることはできますか？
特定の失敗した期間を回収する加盟店向けエンドポイントはありません。 サブスクリプション API はcreate、inquiry、cancel、manage、change、change/inquiry、update で構成されており — いずれも期間の課金を再駆動せず、「今すぐ支払う」や「再支払い」の呼び出しはありません。
実際にできることは次のとおりです。
有効な決済手段を追加することが最も価値の高い行動です。紐付けられたバックアップは、再試行間隔を待つのではなく、次の失敗時に直ちに試行されるからです。
再試行ポリシーを Portal で自分で変更できますか？
いいえ。再試行戦略 — サイクルごとの間隔と最大試行回数 — は収単契約上にあり、Waffo が設定します。それを書き換える Portal 画面も API もないため、セルフサービスでは変更できず、リクエストごとのパラメータでもありません。 契約上の他のスケジュールを形作る設定についても同様です。上記の支払い後の再基準化の動作、およびサブスクリプションがキャンセルされたときに保留中の再試行をクローズするかどうかです。3 つすべてがアカウントレベルです。いずれかが変更された場合、既存のサブスクリプションにも適用されるのか、新規のものだけなのかを明確に確認してください — 答えはどの設定かによって異なり、誤った前提を置くことが照合が崩れる原因になります。実際のサイクルを待たずに、これらすべてをテストするにはどうすればよいですか？
サンドボックスの更新シミュレーターを使用してください。サブスクリプションをアクティブ化し、/api/v1/subscription/manage で管理 URL を取得して開き、次回支払いシミュレーションのコントロールで 1 期間ずつ進めます。1 クリックが 1 期間なので、「期間 2 は成功、期間 3 は失敗」のように連鎖させることができます。詳細と予約されたテスト金額はサンドボックスシミュレーターとサンドボックステストに記載されています。
サンドボックスでできないのは実際の時計を早送りすることです。そのため上記の月末の動作は、待つのではなく、シミュレートした各期間の後に nextPaymentDateTime を読み取ることで検証するのが最善です — 31 日に開始したサブスクリプションは、2 月には 28 日／29 日、3 月には再び 31 日を示すはずです。