> ## 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 Subscription を使用するサブスクリプション（定期課金）の連携手順を説明します。この方式を選択した後、上から順に進めれば連携が完了します。各セクションではそのステップの判断ポイントと注意点のみを扱い、フィールド定義や列挙値は該当のリファレンスページへリンクし、ここでは繰り返しません。 都度決済の導入手順は[純粋な API 連携の概要](/docs/ja/developer-docs/integration/api/overview)をご参照ください。 ## サブスクリプション連携方式の選択 Waffo では、サブスクリプションを次の 2 つの方式で連携できます。まず、サブスクリプションの管理主体を選択してください。 | 連携方式 | サブスクリプションの管理主体 | 課金方法 | 次のステップ | | - | - | - | - | | Waffo Subscription | Waffo | 決済手段の機能に応じて Waffo が更新課金を処理 | 本ページを続けて読む | | 加盟店管理サブスクリプション | 加盟店 | Token を保存し、自社のスケジュールに従って MIT を開始 | [Waffo Checkout でのカード登録](/docs/ja/developer-docs/integration/tokenization/checkout-card-binding)または[加盟店側のカード登録](/docs/ja/developer-docs/integration/tokenization/overview)へ進む | Waffo Subscription は加盟店に統一された連携方式を提供します。実際の更新課金は Waffo または決済チャネルが実行する場合があります。決済手段ごとの少数の機能差は、[サブスクリプション決済手段の比較](/docs/ja/developer-docs/tools-and-references/references/subscription-payment-methods)をご参照ください。 加盟店管理サブスクリプションでは `/api/v1/subscription/*` を使用しません。自社システムで課金スケジュール、サブスクリプションのステータス、失敗時の再試行、プラン変更、解約を管理します。各期では、カード登録で取得した Token を使用し、`ONE_TIME_PAYMENT` で MIT を開始します。Token のライフサイクル、CIT 検証、MIT リクエスト、決済結果の確認はカード登録ドキュメントに記載しているため、本ページでは繰り返しません。 Waffo Subscription を選択した場合は、次の手順に従って連携してください。 ```mermaid theme={null} flowchart LR A[モデルを選定] --> B[周期とトライアルを設定] B --> C[作成と承認] C --> D[通知を受信] D --> E[更新と再試行に対応] E --> F[サンドボックス検証と検収] ``` ## 連携前に確認すべき 3 点 | 確認項目 | 確認先 | | - | - | | 利用する決済手段がサブスクリプションに対応しているか、対応範囲はどこまでか | [サブスクリプション決済手段の比較](/docs/ja/developer-docs/tools-and-references/references/subscription-payment-methods) | | 自社ビジネスが決済優先かサービス優先か | 本ページの[サブスクリプションモデルの選定](#サブスクリプションモデルの選定) | | 課金サイクルを `periodType` + `periodInterval` で表現できるか | 本ページの[課金周期とトライアル期間の設定](#課金周期とトライアル期間の設定) | サブスクリプションが利用可能か、および各決済手段の具体的な機能は、最終的に加盟店の契約設定と [`POST /api/v1/paymethodconfig/inquiry`](/docs/api-reference/pay-method-config-inquiry/pay-method-config-inquiry) のレスポンス結果に従います。 ## サブスクリプションモデルの選定 Waffo は 2 つのサブスクリプションモデルを提供しています。主な違いは、**更新失敗後のサービス提供と課金の処理**です。選択を誤ると、権益の切り替えや請求のリズムが想定とずれるため、連携前に決めておく必要があります。 | | 決済優先 | サービス優先 | | - | - | - | | 当期の課金が失敗したとき | ユーザーの権益を停止 | サービスを継続提供 | | 後続の周期 | 以降の課金を発行しない | 当初の計画どおり発行 | | 再試行成功後の次期起算点 | 再試行の成功日時から再起算 | 当初予定の課金基準を維持 | | 複数期の請求の並存 | 不可 | 可 | 次の 2 つの質問でどちらに該当するか判断できます。 1. 第 2 期の課金予定が 7 月 1 日で、失敗が続き 7 月 3 日に成功したとします。この 2 日間、ユーザーの権益を停止しますか（決済優先）、それともサービスを継続提供しますか（サービス優先）？ 2. ある期の更新が完全に失敗した場合、後続の周期も課金を続けますか？ 停止するなら決済優先、続けるならサービス優先です。 連携前に決済優先またはサービス優先を選択し、希望するモデルを Waffo にお伝えください。モデルの確認や変更が必要な場合は、Waffo テクニカルサポートまでお問い合わせください。 PIX はサービス優先のみに対応し、その他の決済手段は両方に対応しています。[サブスクリプション決済手段の比較](/docs/ja/developer-docs/tools-and-references/references/subscription-payment-methods)をご参照ください。 ## 課金周期とトライアル期間の設定 周期は `productInfo.periodType` と `productInfo.periodInterval` の組み合わせで表現します。 | periodType | periodInterval の指定範囲 | | - | - | | `DAILY` | 1〜365 | | `WEEKLY` | 1〜4 | | `MONTHLY` | 1 以上、上限なし | **`YEARLY` タイプはありません。** 年次サブスクリプションは `MONTHLY` + `periodInterval: "12"` で表現します。同様に四半期は `3`、半年は `6`、2 年は `24` です。 その他の周期関連フィールド： * `numberOfPeriod` — 総期数。空欄の場合は無期限のサブスクリプションになります。 * `trialPeriodAmount` — トライアル期間の 1 期あたりの金額。0 以上かつ正規期間の金額未満である必要があります。空欄の場合はトライアル期間なし、`0` を指定すると無料トライアルになります。 * `numberOfTrialPeriod` — トライアル期間の期数。 * `trialPeriodType` / `trialPeriodInterval` — トライアル期間の周期タイプと間隔。正規期間と異なる設定が可能です（例：週次トライアルから月次課金へ）。空欄の場合は正規期間の値を継承します。PIX ではトライアル期間の頻度を正規期間と一致させる必要があります。 * `scheduledAmounts` — 期ごとの金額リストで、要素は `{period, amount}` です。初回割引や段階的な値上げなど、期ごとに金額が異なる場合に使用します。全期間同額であれば指定不要です。このフィールドは、対応する Waffo 管理サブスクリプションでのみ使用できます。PIX や DANA などのチャネル管理サブスクリプションでは使用できません。 フィールド定義の詳細は[サブスクリプションの作成](/docs/api-reference/subscription-create/create-subscription)をご参照ください。 ## サブスクリプションの作成と承認への対応 [`POST /api/v1/subscription/create`](/docs/api-reference/subscription-create/create-subscription) を呼び出してサブスクリプションを作成します。周期パラメータ以外で、特に問題が起きやすいフィールドは次のとおりです。 * `subscriptionRequest` — サブスクリプションの冪等キーで、加盟店側で生成します。作成リクエストを再試行する際は同じ値を再利用してください。[冪等性](/docs/ja/developer-docs/core-concepts/idempotency)をご参照ください。 * `currency` と `amount` — サブスクリプションで使うのは `currency` と `amount` であり、都度決済の `orderCurrency` と `orderAmount` では**ありません**。このフィールド名の混同が最も多い連携エラーです。 * `paymentInfo.payMethodType` — 任意です。指定した場合は決済手段タイプで候補を絞り込みます。省略した場合、タイプによる絞り込みは行いません。`paymentInfo.payMethodName` も省略した場合に限り、Waffo は加盟店契約に基づいて利用可能なすべての決済手段を表示します。 * `userInfo.userEmail` — 必須です。実在のメールアドレスがない場合は、ユーザー ID から生成した一意のフォールバックアドレスを指定してください。プレースホルダー値の使用や、複数ユーザーで同一アドレスの共用は避けてください。 * `subscriptionManagementUrl` — 必須で、かつ認証のあるページである必要があります（公開 URL は不可）。PC では開けないため、ディープリンクではなく Web の URL を指定してください。自社のサブスクリプション管理ページを使うことも、[`POST /api/v1/subscription/manage`](/docs/api-reference/subscription-manage/subscription-manage) が返す URL をラップして渡すこともできます。 * `notifyUrl` — Webhook のコールバックアドレスです。本ページの[通知の受信](#通知の受信)をご参照ください。 ### 承認リダイレクトへの対応 レスポンスの `subscriptionStatus` が `AUTHORIZATION_REQUIRED` の場合、ユーザーによる承認が必要であり、承認ページへリダイレクトする必要があります。承認先のアドレスは `subscriptionAction` フィールドに含まれますが、これは **JSON 文字列**です。先にパースしてから `webUrl` を取得してください。 ```json theme={null} { "code": "0", "msg": "Success", "data": { "subscriptionRequest": "sub_a1b2c3d4e5f6a1b2c3d4e5f6", "subscriptionId": "SUB20260805000001", "subscriptionStatus": "AUTHORIZATION_REQUIRED", "subscriptionAction": "{\"webUrl\":\"https://cashier.waffo.com/subscribe?token=xxx\"}" } } ``` `subscriptionAction` をオブジェクトとして直接プロパティ参照しないでください。文字列であるため、必ず JSON パースが必要です。同じ扱いがサブスクリプション照会、サブスクリプション変更、変更照会のレスポンスにも当てはまります。 ## サブスクリプションのステータスと加盟店側の対応 サブスクリプションには 8 つのステータスがあります。各ステータスでの対応は[決済ライフサイクル](/docs/ja/developer-docs/core-concepts/payment-lifecycle#サブスクリプションのステータス)、各ステータスが終了状態かどうかは[データリファレンス](/docs/ja/developer-docs/tools-and-references/references/data-reference#サブスクリプションステータス)をご参照ください。 作成 API の同期レスポンスだけでサブスクリプションの最終ステータスを判断しないでください。有効化・解約・クローズはいずれも Webhook で通知されます。または [`POST /api/v1/subscription/inquiry`](/docs/api-reference/subscription-inquiry/subscription-inquiry) で能動的に照会して確認してください。 ## 通知の受信 サブスクリプションには 3 種類の通知があり、必要な粒度に応じて受信対象を選択します。それぞれの発火タイミング、適した用途、推奨の組み合わせは [Webhook イベントタイプ](/docs/ja/developer-docs/webhook/event-types#サブスクリプション通知の選択ガイド)をご参照ください。 重要な制約：`SUBSCRIPTION_STATUS_NOTIFICATION` と `SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` はいずれも非同期で配信され、**到達順序は保証されません**。コールバックの到達順序を業務ステートマシンの根拠にしないでください。正しい対応方法（冪等な重複排除、いずれかのコールバック受信後にまず最終ステータスを照会する）は [Webhook 処理のベストプラクティス](/docs/ja/developer-docs/webhook/best-practices)をご参照ください。 ## 更新失敗と再試行 更新課金が失敗した場合に Waffo と決済チャネルのどちらが再試行するかは、更新管理方式によって決まります。 **Waffo 管理サブスクリプション**では、Waffo が当期の課金を自動的に再試行します。加盟店側で再試行を実装する必要はありません。 * 再試行ポリシーは課金サイクルごとに区分して設定され、各区分に**最大再試行回数**と**再試行間隔**が含まれます。 * 再試行間隔の単位は**日**です。時間単位の再試行間隔設定は存在しません。 * カスタマイズしていない場合、当期の初回課金失敗後、1 日ごとに最大 5 回再試行します。再試行回数または間隔のカスタマイズが必要な場合は、Waffo のアカウントマネージャーまたはテクニカルサポートへお問い合わせください。このポリシーは API パラメータでは変更できません。 * 再試行成功後の次期起算点と、再試行回数を使い切った後に後続周期の課金を継続するかどうかは、[サブスクリプションモデル](#サブスクリプションモデルの選定)によって決まります。Waffo 管理の更新日時の計算ルールは、[サブスクリプション決済手段の比較](/docs/ja/developer-docs/tools-and-references/references/subscription-payment-methods#waffo-管理の更新日時の計算方法)をご参照ください。 **チャネル管理サブスクリプション**では、決済チャネル独自のルールで再試行します。PIX と DANA はウォレット側の再試行ルールを使用し、加盟店によるカスタマイズには対応していません。詳細は[サブスクリプション決済手段の比較](/docs/ja/developer-docs/tools-and-references/references/subscription-payment-methods)をご参照ください。 Waffo 管理サブスクリプションでは、通知の粒度に注意してください。再試行中の**各回**の課金失敗ごとに `PAYMENT_NOTIFICATION` が送信されます。各期の最終結果のみを把握したく、途中の再試行が不要であれば、`SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION` を受信してください。 ## 変更・修正・解約 この 3 つは用途の異なる別 API です。混同しないでください。 | やりたいこと | 使用する API | ポイント | | - | - | - | | プラン変更（アップグレード / ダウングレード） | [`POST /api/v1/subscription/change`](/docs/api-reference/subscription-change/subscription-change) | 新しい `subscriptionRequest`、元のサブスクリプションの `originSubscriptionRequest`、`remainingAmount`（元のサブスクリプションの残存価値を新プランへ充当する金額）、`productInfoList`（新プラン）が必要です。`startTime` で適用開始時刻を指定でき、空欄の場合は即時適用です。`promotionInfo` でプロモーションを適用できます。`AUTHORIZATION_REQUIRED` が返る場合は[承認リダイレクトへの対応](#承認リダイレクトへの対応)に従って処理してください。完了時に `SUBSCRIPTION_CHANGE_NOTIFICATION` が送信されます。 | | 金額調整または差額請求 | [`POST /api/v1/subscription/update`](/docs/api-reference/subscription-update/subscription-update) | `subscriptionRequest` または `subscriptionId` でサブスクリプションを特定します。通常の金額調整には `amount`、`productInfo.trialPeriodAmount`、`productInfo.scheduledAmounts` を使用します。`topupInfo` を指定すると当期の差額注文を作成し、支払い成功後に後続期間へ新しい金額を適用します。 | | 加盟店側からの解約 | [`POST /api/v1/subscription/cancel`](/docs/api-reference/subscription-cancel/subscription-cancel) | `subscriptionId`、`merchantId`、`requestedAt` を指定します。すべての決済手段が加盟店側からの解約に対応しています。 | | ユーザーに管理入口を提供 | [`POST /api/v1/subscription/manage`](/docs/api-reference/subscription-manage/subscription-manage) | サブスクリプション管理ページの URL を返します。サブスクリプションが処理中または失敗している場合、この URL は利用できず `A0028` が返ります。 | ### よくある金額調整のシナリオ `update` は `ACTIVE` 状態の Waffo 管理サブスクリプションでのみ利用できます。各リクエストでは `amount`、`productInfo.trialPeriodAmount`、`productInfo.scheduledAmounts` のうち少なくとも 1 つを指定してください。`topupInfo` を同時に指定する場合も、差額支払い成功後に適用する目標金額が必要です。直接の金額変更は将来の請求に適用されます。当期の注文はすでに作成済みのため、直接変更できません。 | シナリオ | 指定するフィールド | 適用方法 | | - | - | - | | 後続期間を同じ金額へ一括変更 | `amount` | 次期から新しい金額を使用します。同じ期が `scheduledAmounts` にも指定されている場合は、期別の金額が優先されます。 | | 1 つまたは複数の将来期間のみ一時的に変更 | `productInfo.scheduledAmounts`（例：第 4 期だけ割引） | 各 `period` は現在の期より後である必要があり、最大 10 件です。未指定の期は `amount` を使用します。送信したリストで保存済みリストを置き換えるため、維持したい他の将来期の特別金額も含めてください。 | | 終了前のトライアル金額を変更 | `productInfo.trialPeriodAmount` | トライアル期間中のみ利用でき、次期から適用されます。 | | 当期に席数を追加し、後続期間の金額も増額 | 将来期間の新しい `amount` と `topupInfo` | Waffo は当期差額の即時支払い注文を作成します。差額の支払い成功後にのみ、新しい `amount` が次期から適用されます。差額注文がクローズまたは失敗した場合、後続期間の金額は変更されません。 | 当期の席数追加に対する差額請求の例： ```json theme={null} { "subscriptionId": "SUB20260920000001", "amount": "130.00", "topupInfo": { "topupRequest": "seat-topup-001", "topupAmount": "15.00", "description": "当期に 3 席を追加した差額" } } ``` `topupAmount` は加盟店が計算する当期の差額で、0 より大きい必要があります。`amount` は差額支払い成功後に後続期間で使用する新しい合計金額です。`topupRequest` は差額注文の冪等キーで、同じリクエストを再試行するときは再利用してください。レスポンスの `topupInfo.topupStatus` が `AUTHORIZATION_REQUIRED` の場合、`topupInfo.topupAction` を JSON 文字列として解析し、その `webUrl` へユーザーをリダイレクトします。同じサブスクリプションで同時に処理できる差額注文は 1 件のみです。 一部の決済手段では、ユーザーが決済手段側で自ら解約できます（Apple Wallet、Google Pay、PayPay アプリなど）。解約状態は Waffo に連携され、`CHANNEL_CANCELLED` または `USER_CANCELLED` として反映されます。ユーザー側解約に対応する決済手段は[サブスクリプション決済手段の比較](/docs/ja/developer-docs/tools-and-references/references/subscription-payment-methods)をご参照ください。 ## サンドボックス検証と検収 都度決済と同様に、キャッシャーページで操作します。 `POST /api/v1/subscription/manage` で管理ページの URL を取得して開き、ページ上の「次回決済成功をシミュレート」「次回決済失敗をシミュレート」ボタンで期ごとにシミュレートします。手順は[サンドボックスとテスト](/docs/ja/developer-docs/getting-started/sandbox)および[サンドボックスシミュレーター](/docs/ja/developer-docs/tools-and-references/developer-tools/sandbox-simulator)をご参照ください。 [連携検収基準](/docs/ja/developer-docs/tools-and-references/references/acceptance-criteria)に従ってサブスクリプションの検収ケースを実施し、サブスクリプション決済の検収ケーステンプレートに記入のうえ、Waffo テクニカル連携グループへ提出してください。 本番公開前に、少なくとも次の点を確認してください。初回期間の成功・失敗の両経路、サブスクリプションステータス通知とサブスクリプション決済通知の署名検証、`subscriptionRequest` と期数による該当周期注文の突合、および Unknown ステータス時に自社でサブスクリプションをクローズしないこと。 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.