Skip to main content
このページでは、Waffo のサブスクリプションについて加盟店から最もよく寄せられる質問に回答します。項目レベルの仕様は Subscription API 仕様 にあります。

​
ユーザーのプランをアップグレードまたはダウングレードするにはどうすればよいですか？

/api/v1/subscription/change を呼び出します。変更リクエストは元のサブスクリプションを基にした新しいサブスクリプションを 作成し、元のサブスクリプションの残額は新しいものに充当されます — 手動でキャンセルして作り直す必要はありません。
  • 結果は /api/v1/subscription/change/inquiry で追跡してください。
  • 変更が完了すると、Waffo は SUBSCRIPTION_CHANGE_NOTIFICATION も送信します。

​
change、update、manage の違いは何ですか？

金額の更新は契約上の上限に対して検証されます。

​
期間ごとに異なる金額を請求できますか？

はい。2 つの仕組みを組み合わせて、段階的な価格設定や初回期間の特典に対応できます。
  • トライアル期間 — サブスクリプション作成時に trialPeriodAmount と numberOfTrialPeriod を設定します。 トライアルの粒度は trialPeriodType と trialPeriodInterval でカスタマイズできます。
  • 予定金額 — 特定の正規期間（たとえば割引される初回期間）について、作成時または後から /api/v1/subscription/update で期間ごとの金額を設定します。
ある期間に予定金額が設定されていない場合は、サブスクリプションの基本 amount が適用されます。

​
引き落としが失敗しました。次に何が起きますか？

失敗した引き落としは、サブスクリプションのリトライ戦略に従って自動的にリトライされます — お客様がリトライを 起動する必要はありません。
  • 失敗理由、タイムスタンプ、リトライの詳細を含むすべての決済試行は、サブスクリプション決済注文の通知で送信されます。
  • 各請求期間の最終結果だけが必要な場合は、代わりに SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION を購読してください — 期間ごとに 1 回、最終結果とともに送信され、途中のリトライイベントはスキップされます。
具体的なリトライのスケジュールと上限は、契約に設定されたリトライ戦略によって異なります。お客様のアカウントの正確な ポリシーが必要な場合は、インテグレーションサポートにお問い合わせください。

​
どのサブスクリプション通知を購読すべきですか？

いずれの通知でも、処理後に success を返してください。Waffo が failed または unknown を受け取った場合、 Waffo は翌日にかけて分散したバックオフのスケジュールで通知をリトライします。スケジュールは Webhook のリトライ を参照してください。

​
ユーザーはどのようにサブスクリプションを解約しますか？

2 つの経路があります。
  • 加盟店から — /api/v1/subscription/cancel を呼び出します。
  • ユーザーから — /api/v1/subscription/manage で取得したホスト型管理ページへユーザーをリダイレクトすると、 そこで詳細の確認と解約ができます。
  • ウォレット側から — ユーザーがウォレットアプリ内で支払いの認可を取り消すと、ウォレットが Waffo に通知します。 取り消された決済手段がそのサブスクリプションで唯一のものだった場合、サブスクリプションは自動的に解約されます。 バックアップの決済手段がある場合は、そちらがデフォルトになります。これはサブスクリプションステータス通知で お客様に通知されるため、サブスクリプションがまだ有効かどうかについては、自社の記録ではなく Webhook を正としてください。
サブスクリプションが解約状態に到達すると、新しい請求期間は開かれません。すでに保留中のリトライが即座に破棄されるかどうかは 契約上の設定によります — 重要な場合はインテグレーションサポートに確認してください。

​
Waffo は日次請求や異通貨のサブスクリプションに対応していますか？

どちらも対応しています。
  • DAILY は他の請求サイクルと並ぶサポート済みの periodType です。
  • 異通貨のサブスクリプションは userCurrency 項目でサポートされます — ユーザーは自国通貨で支払います。
決済手段ごとの機能と制限は、Subscription API 仕様 の付録に記載されています。

​
subscriptionManagementUrl には何を渡すべきですか？

subscriptionManagementUrl はサブスクリプション作成時に必須として文書化されており、常に送信すべきです。 ただし、サーバーは現在これを省略したリクエストを拒否しません — 省略は検証エラーとしては現れず、後から お客様のページへ誘導する顧客向けメールのリンクが欠落する形で現れます。デスクトップブラウザでユーザーが開けるページを 指定してください。アプリのディープリンクはここでは不適切です：PC で開いたユーザーがページにまったくたどり着けない 可能性があります。選択肢は 3 つあります。
  • 自社で認証付きのサブスクリプション管理ページを構築し、その URL を渡す。
  • Waffo が /api/v1/subscription/manage から返すホスト型ページを自社のページでラップし、その URL を渡す。
  • Waffo のホスト型管理ページをそのまま使う。
このページは機能の入口であり、決済フローのステップではありません。リアルタイムの取引中に表示されるものではなく、 サブスクリプションの決済が成功した後に — ユーザーのアカウント画面、注文確認ページ、その他サイト上の適切な場所で — 提示するものです。

​
サブスクリプションの通知を受け取りましたが、直後に照会するとサブスクリプションが ACTIVE ではありません

サブスクリプションの状態は結果整合性です。通知が届いた時点では内部の状態更新がまだ収束中のことがあるため、 その直後に発行した照会は、まだ ACTIVE ではないステータスを返すことがあります。これは読み取りのタイミングの影響であり、 サブスクリプションの失敗ではありません。 次のように扱ってください。
  • 最初の照会結果を最終的なものとして扱わないでください。少し待ってから再照会してください。
  • 状態変化のトリガーとしてはサブスクリプションステータス通知を優先し、照会は判断のためではなく確認のために使ってください。

​
トライアル期間の金額を通常の金額と同じにできますか？

いいえ。作成時、trialPeriodAmount は amount より厳密に小さくなければなりません。等しい値は trial period amount should be less than subscription amount というメッセージのパラメーターエラーで拒否されます。 ゼロは有効なトライアル金額（無料トライアル）なので、受け付けられる範囲は 0 ≤ trialPeriodAmount < amount です。 価格を変えずに請求カレンダーをずらすことがトライアルの目的であれば、トライアルはまったく設定せず、 startTime で初回の請求を遅らせるか、scheduledAmounts で初期の特定期間の価格を設定してください。