どのような課金サイクルを設定できますか？
periodType と periodInterval の組み合わせでサイクルの長さが定義されます。どちらも必須で、受け付けられる periodInterval の範囲は periodType によって異なります：
YEARLY という期間タイプはありません。 年間サブスクリプションには、periodType: MONTHLY と periodInterval: 12 を使用してください。
加盟店からよく名前で尋ねられるサイクルも、この 2 つのフィールドで対応できます：
個々の決済手段によってはさらに制限が狭まる場合があります。日次サイクルを拒否するものや、特定のサイクル/間隔の組み合わせしか受け付けないものもあります。上記の範囲を満たすサイクルでも、選択した決済手段によっては拒否されることがあります。
トライアル期間に通常期間と異なるサイクルを使用できますか？
はい。トライアルのサイクルは、trialPeriodType と trialPeriodInterval によって通常のサイクルとは独立して設定され、受け付けられる範囲は通常期間と同じです：
trialPeriodTypeとtrialPeriodIntervalは同時に指定する必要があります。片方だけの指定は拒否されます。- 両方を省略した場合、トライアルは
periodTypeとperiodIntervalをそのまま再利用します。 - 独立して設定できるからといって、相互チェックがないわけではありません。次の質問をご覧ください。
同時に指定しなければならないサブスクリプションのフィールドはどれですか？
また、トライアルサイクルは独立して設定されるものの、以下のフィールド間ルールが適用されます：
サブスクリプションは何期間まで継続できますか？
「加盟店が定義した終了はない」といっても、文字どおり無制限ではありません。
numberOfPeriod のないサブスクリプションも、サブスクリプション契約の最大期間によって制限されており、Waffo はその期間と貴社のサイクルから実効的な最終期間数を導出します。決済手段によっては、独自の最大期間を課すものもあります。そのため、終了を設定していなくても、いずれ最終期間に達することを前提に設計してください。
サブスクリプションが最終期間に達すると、金額の更新は拒否されます。金額ページをご覧ください。
サブスクリプション作成時に goodsUrl と appName は必須ですか？
いいえ。 /api/v1/subscription/create ではどちらもオプションであり、両方なしでもサブスクリプションを作成できます。
ご覧になったことがあるかもしれない「goodsUrl または appName のいずれかを指定する」というルールは、サブスクリプション作成ではなく、ワンタイム注文の作成に属するものです。個々の契約ではコンプライアンスやリスク上の理由から goodsUrl を必須とする場合があるため、いずれか一方を指定することは引き続き良い慣行です。ただし、これはサブスクリプション作成の一律の検証ではなく、そうであるかのように連携を構築すると、拒否をデバッグする際に誤った方向へ導かれます。
サブスクリプションのステータスにはどのようなものがあり、どの遷移が有効ですか？
9 つのステータスが存在します。各ステータスには到達可能な特定の元ステータスが定められているため、予期しないステータスが表示された場合、通常は無効な状態の兆候ではなく、以前の遷移を見逃した兆候です：
貴社の連携で必要になると思われる形でグループ化すると：
終端グループ全体を「今後新たな課金期間は開始されない」と扱い、個々の値ではなくグループで分岐してください。そうすれば、マッピングしていないステータスが知らないうちに有効なサブスクリプションのように見えることはありません。
PLATFORM_CANCELLED とは何ですか？
そのサブスクリプションのいずれかの課金で異議申し立て、チャージバック、または不正シグナルが発生したため、Waffo が自らの判断でサブスクリプションをキャンセルした際に設定する終端ステータスです。他のキャンセルと同様にサブスクリプションステータス通知を通じて届き、通知にはどの種類のシグナルがトリガーとなったかを示すキャンセル理由が含まれます。
連携上重要なポイント：
ACTIVEからのみ到達可能です。- 自動キャンセルは加盟店ごと、シグナルタイプごとに設定可能で、設定されていない限りオフです。そのため、この値を目にすることが一度もない可能性があり、この値がないことは異議申し立てが無視されていることを意味しません。
- 貴社ではなく Waffo が開始したものであるため、通知を処理するまで貴社側の記録ではサブスクリプションが有効と表示されます。Webhook を正となる情報源として扱ってください。
作成時に AUTHORIZATION_REQUIRED が返されました。どうすればよいですか？
ユーザーはまだ継続課金の委任（マンデート）を認可する必要があります。作成レスポンスには subscriptionAction が含まれ、その中にユーザーを送るべき URL（webUrl）があります。ユーザーをそこへリダイレクトしてください。認可が成功すると、サブスクリプションは ACTIVE に移行します。
subscriptionAction は、サブスクリプションが IN_PROGRESS または AUTHORIZATION_REQUIRED の間のみ設定されます。サブスクリプションが有効または終端になると返されなくなりますが、これはエラーではなく想定どおりの動作です。
認可リンクには時間制限があります。作成リクエストの orderExpiredAt がその期限を設定します。省略した場合はプラットフォームのデフォルトが適用されますが、これは短く、数時間ではなく数分単位です。そのため、ユーザーをすぐにリンクへ送ってください。期限内に認可が完了しなかったサブスクリプションは CLOSE に移行します。
同じリクエスト ID で create を再度呼び出すとどうなりますか？
作成は、貴社が生成するリクエスト ID であるsubscriptionRequest に対して冪等であり、merchantSubscriptionId に対してではありません。同じ MID の下で同じ subscriptionRequest を使って再度呼び出しても、2 つ目のサブスクリプションは作成されません。
返される内容は、既存のサブスクリプションがどこまで進んでいるかによって異なります：
再呼び出しでは整合性も検証されます。
amount または currency が元のリクエストと異なる場合、黙って受け付けられるのではなく重複として拒否されます。そのため、同一のペイロードでリトライし、1 つの subscriptionRequest を 2 つの異なるサブスクリプションで再利用しないでください。
ユーザーが認可を途中で放棄し、新しいリンクを渡す必要がある場合は、サブスクリプションがまだ有効化前の状態のうちに作成をリトライし、返ってきた subscriptionAction を使用してください。リンクをキャッシュして有効なままだと想定しないでください。
サブスクリプションを照会し、期間ごとの課金を取得するにはどうすればよいですか？
/api/v1/subscription/inquiry を subscriptionRequest または subscriptionId を指定して呼び出します。少なくとも一方が必須です。両方を渡すことも受け付けられます。
期間ごとの課金はデフォルトでは返されません。取得するには paymentDetails を 1 に設定してください（デフォルトの 0 では省略され、それ以外の値は拒否されます）：
各
paymentDetails エントリには acquiringOrderId、orderCurrency、orderAmount、orderStatus、orderUpdatedAt、period が含まれ、追加（シート追加）課金があった期間には topupDetails リストも含まれます。これらの行の番号付けについては
通貨をまたぐサブスクリプションと Portal FAQ
をご覧ください。
逆方向、つまり課金からそのサブスクリプションを辿る場合、注文照会レスポンスには subscriptionId、period、subscriptionRequest、およびその課金が期間課金か決済手段の追加かを示す subscriptionEvent を含む subscriptionInfo ブロックが含まれます。ワンタイム注文には subscriptionInfo はありません。
サブスクリプションレスポンスには productInfo.currentPeriod と保存済みの productInfo.scheduledAmounts も含まれ、これは金額変更をスケジュールする前に読み取るものです。
1 人のユーザーは何件のサブスクリプションを持てますか？
いくつでも持てます。1 つの MID の下で、同じmerchantUserId は貴社が作成した数だけサブスクリプションを保持できます。ユーザーごとの上限はなく、作成時に merchantUserId の一意性チェックも行われません。
これは複数商品・複数シートのビジネスでは通常の形です。1 人のユーザーが複数のサブスクリプションを同時に持ち、それぞれが独自の subscriptionId と独自のライフサイクルを持ちます。そのため、merchantUserId を「そのユーザーのサブスクリプション」のキーとして扱わないでください。subscriptionId または貴社独自の merchantSubscriptionId をキーにしてください。
サブスクリプションを将来の日付から開始できますか？
はい。作成時にstartTime を渡してください。検証：
過去日付への設定（バックデート）はサポートされていません。 以前に開始したかのように動作するサブスクリプションを作成する方法はなく、最初の期間を過去に設定する方法もありません。すでに経過した期間に対して請求する必要がある場合は、別のワンタイム注文として回収してください。
開始を先延ばしする場合のさらに 2 つの制約：
- 開始日は、使用される契約の有効期間内に収まっていなければなりません。そのため、365 日以内であっても、遠い開始日はその理由で拒否されることがあります。
- プラン変更の場合、
startTimeは元のサブスクリプションの次回予定課金より前であってはなりません。