サブスクリプション連携方式の選択
Waffo では、サブスクリプションを次の 2 つの方式で連携できます。まず、サブスクリプションの管理主体を選択してください。
Waffo Subscription は加盟店に統一された連携方式を提供します。実際の更新課金は Waffo または決済チャネルが実行する場合があります。決済手段ごとの少数の機能差は、サブスクリプション決済手段の比較をご参照ください。
加盟店管理サブスクリプションでは
/api/v1/subscription/* を使用しません。自社システムで課金スケジュール、サブスクリプションのステータス、失敗時の再試行、プラン変更、解約を管理します。各期では、カード登録で取得した Token を使用し、ONE_TIME_PAYMENT で MIT を開始します。Token のライフサイクル、CIT 検証、MIT リクエスト、決済結果の確認はカード登録ドキュメントに記載しているため、本ページでは繰り返しません。
Waffo Subscription を選択した場合は、次の手順に従って連携してください。
連携前に確認すべき 3 点
サブスクリプションが利用可能か、および各決済手段の具体的な機能は、最終的に加盟店の契約設定と
POST /api/v1/paymethodconfig/inquiry のレスポンス結果に従います。サブスクリプションモデルの選定
Waffo は 2 つのサブスクリプションモデルを提供しています。主な違いは、更新失敗後のサービス提供と課金の処理です。選択を誤ると、権益の切り替えや請求のリズムが想定とずれるため、連携前に決めておく必要があります。
次の 2 つの質問でどちらに該当するか判断できます。
- 第 2 期の課金予定が 7 月 1 日で、失敗が続き 7 月 3 日に成功したとします。この 2 日間、ユーザーの権益を停止しますか（決済優先）、それともサービスを継続提供しますか（サービス優先）？
- ある期の更新が完全に失敗した場合、後続の周期も課金を続けますか？ 停止するなら決済優先、続けるならサービス優先です。
連携前に決済優先またはサービス優先を選択し、希望するモデルを Waffo にお伝えください。モデルの確認や変更が必要な場合は、Waffo テクニカルサポートまでお問い合わせください。
課金周期とトライアル期間の設定
周期はproductInfo.periodType と productInfo.periodInterval の組み合わせで表現します。
その他の周期関連フィールド：
numberOfPeriod— 総期数。空欄の場合は無期限のサブスクリプションになります。trialPeriodAmount— トライアル期間の 1 期あたりの金額。0 以上かつ正規期間の金額未満である必要があります。空欄の場合はトライアル期間なし、0を指定すると無料トライアルになります。numberOfTrialPeriod— トライアル期間の期数。trialPeriodType/trialPeriodInterval— トライアル期間の周期タイプと間隔。正規期間と異なる設定が可能です（例：週次トライアルから月次課金へ）。空欄の場合は正規期間の値を継承します。PIX ではトライアル期間の頻度を正規期間と一致させる必要があります。scheduledAmounts— 期ごとの金額リストで、要素は{period, amount}です。初回割引や段階的な値上げなど、期ごとに金額が異なる場合に使用します。全期間同額であれば指定不要です。このフィールドは、対応する Waffo 管理サブスクリプションでのみ使用できます。PIX や DANA などのチャネル管理サブスクリプションでは使用できません。
サブスクリプションの作成と承認への対応
POST /api/v1/subscription/create を呼び出してサブスクリプションを作成します。周期パラメータ以外で、特に問題が起きやすいフィールドは次のとおりです。
subscriptionRequest— サブスクリプションの冪等キーで、加盟店側で生成します。作成リクエストを再試行する際は同じ値を再利用してください。冪等性をご参照ください。currencyとamount— サブスクリプションで使うのはcurrencyとamountであり、都度決済のorderCurrencyとorderAmountではありません。このフィールド名の混同が最も多い連携エラーです。paymentInfo.payMethodType— 任意です。指定した場合は決済手段タイプで候補を絞り込みます。省略した場合、タイプによる絞り込みは行いません。paymentInfo.payMethodNameも省略した場合に限り、Waffo は加盟店契約に基づいて利用可能なすべての決済手段を表示します。userInfo.userEmail— 必須です。実在のメールアドレスがない場合は、ユーザー ID から生成した一意のフォールバックアドレスを指定してください。プレースホルダー値の使用や、複数ユーザーで同一アドレスの共用は避けてください。subscriptionManagementUrl— 必須で、かつ認証のあるページである必要があります（公開 URL は不可）。PC では開けないため、ディープリンクではなく Web の URL を指定してください。自社のサブスクリプション管理ページを使うことも、POST /api/v1/subscription/manageが返す URL をラップして渡すこともできます。notifyUrl— Webhook のコールバックアドレスです。本ページの通知の受信をご参照ください。
承認リダイレクトへの対応
レスポンスのsubscriptionStatus が AUTHORIZATION_REQUIRED の場合、ユーザーによる承認が必要であり、承認ページへリダイレクトする必要があります。承認先のアドレスは subscriptionAction フィールドに含まれますが、これは JSON 文字列です。先にパースしてから webUrl を取得してください。
サブスクリプションのステータスと加盟店側の対応
サブスクリプションには 8 つのステータスがあります。各ステータスでの対応は決済ライフサイクル、各ステータスが終了状態かどうかはデータリファレンスをご参照ください。通知の受信
サブスクリプションには 3 種類の通知があり、必要な粒度に応じて受信対象を選択します。それぞれの発火タイミング、適した用途、推奨の組み合わせは Webhook イベントタイプをご参照ください。 重要な制約：SUBSCRIPTION_STATUS_NOTIFICATION と SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION はいずれも非同期で配信され、到達順序は保証されません。コールバックの到達順序を業務ステートマシンの根拠にしないでください。正しい対応方法（冪等な重複排除、いずれかのコールバック受信後にまず最終ステータスを照会する）は Webhook 処理のベストプラクティスをご参照ください。
更新失敗と再試行
更新課金が失敗した場合に Waffo と決済チャネルのどちらが再試行するかは、更新管理方式によって決まります。 Waffo 管理サブスクリプションでは、Waffo が当期の課金を自動的に再試行します。加盟店側で再試行を実装する必要はありません。- 再試行ポリシーは課金サイクルごとに区分して設定され、各区分に最大再試行回数と再試行間隔が含まれます。
- 再試行間隔の単位は日です。時間単位の再試行間隔設定は存在しません。
- カスタマイズしていない場合、当期の初回課金失敗後、1 日ごとに最大 5 回再試行します。再試行回数または間隔のカスタマイズが必要な場合は、Waffo のアカウントマネージャーまたはテクニカルサポートへお問い合わせください。このポリシーは API パラメータでは変更できません。
- 再試行成功後の次期起算点と、再試行回数を使い切った後に後続周期の課金を継続するかどうかは、サブスクリプションモデルによって決まります。Waffo 管理の更新日時の計算ルールは、サブスクリプション決済手段の比較をご参照ください。
変更・修正・解約
この 3 つは用途の異なる別 API です。混同しないでください。よくある金額調整のシナリオ
update は ACTIVE 状態の Waffo 管理サブスクリプションでのみ利用できます。各リクエストでは amount、productInfo.trialPeriodAmount、productInfo.scheduledAmounts のうち少なくとも 1 つを指定してください。topupInfo を同時に指定する場合も、差額支払い成功後に適用する目標金額が必要です。直接の金額変更は将来の請求に適用されます。当期の注文はすでに作成済みのため、直接変更できません。
当期の席数追加に対する差額請求の例：
topupAmount は加盟店が計算する当期の差額で、0 より大きい必要があります。amount は差額支払い成功後に後続期間で使用する新しい合計金額です。topupRequest は差額注文の冪等キーで、同じリクエストを再試行するときは再利用してください。レスポンスの topupInfo.topupStatus が AUTHORIZATION_REQUIRED の場合、topupInfo.topupAction を JSON 文字列として解析し、その webUrl へユーザーをリダイレクトします。同じサブスクリプションで同時に処理できる差額注文は 1 件のみです。
一部の決済手段では、ユーザーが決済手段側で自ら解約できます（Apple Wallet、Google Pay、PayPay アプリなど）。解約状態は Waffo に連携され、CHANNEL_CANCELLED または USER_CANCELLED として反映されます。ユーザー側解約に対応する決済手段はサブスクリプション決済手段の比較をご参照ください。
サンドボックス検証と検収
1
初回決済
都度決済と同様に、キャッシャーページで操作します。
2
更新のシミュレーション
POST /api/v1/subscription/manage で管理ページの URL を取得して開き、ページ上の「次回決済成功をシミュレート」「次回決済失敗をシミュレート」ボタンで期ごとにシミュレートします。手順はサンドボックスとテストおよびサンドボックスシミュレーターをご参照ください。3
検収
連携検収基準に従ってサブスクリプションの検収ケースを実施し、サブスクリプション決済の検収ケーステンプレートに記入のうえ、Waffo テクニカル連携グループへ提出してください。
subscriptionRequest と期数による該当周期注文の突合、および Unknown ステータス時に自社でサブスクリプションをクローズしないこと。