定期課金 – 概要
定期課金とは、本サービスにより定期的かつ自動的に課金することを指します。
オブジェクト名はsubscriptionです。
定期課金の作成（create）リクエストはトランザクショントークンを用いて作成されます。
定期課金は、UPDATEやCANCELのリクエストで、いつでも停止できます。
ウェブフックを用いて、定期課金イベントの通知を受け取ることを推奨します。
- 支払いが成功した時は
SUBSCRIPTION_PAYMENTイベント - 支払いが失敗した時は
SUBSCRIPTION_FAILEDイベント - 定期課金がキャンセルされた時は
SUBSCRIPTION_CANCELEDイベント
で、それぞれ通知します。
“subscription” オブジェクトのデータ構造
| フィールド | データ型 | 備考 |
|---|---|---|
| id | string (UUID) | 定期課金のユニークID 作成時に自動付与 |
| store_id | string (UUID) | 登録された「店舗」のユニークID 契約時に自動付与 |
| transaction_token_id | string (UUID) | 事前に作成したトランザクショントークン |
| amount | number | 課金額 |
| currency | string (ISO-4217) | 通貨 例：日本円はJPY |
| amount_formatted | string | 現実的に流通する補助通貨がある場合、通貨額での課金額 例： currencyがUSDで課金額が110の場合は1.1 |
| initial_amount | number | 初回の課金 ※ CREATE時に未指定だとamountを参照 |
| initial_amount_formatted | string | 現実的に流通する補助通貨がある場合、通貨額での課金額 例： currencyがUSDで課金額が110の場合は1.1 |
| schedule_settings.start_on | string (ISO-8601) | 2回目の課金日 指定日のタイムゾーンの07:00に実行 ※ CREATE時に指定可能 |
| schedule_settings.zone_id | string (IANA Timezone) | タイムゾーン 例：日本は Asia/Tokyo |
| schedule_settings.preserve_end_of_month | boolean | 月末固定の指定が、されている（true）か否（false）か |
| schedule_settings.retry_interval | 半角英数 | 定期課金が失敗したときのリトライ間隔 存在し得る値（意味）： PxD（x日）PxW（x週間）PxM（xか月） |
| schedule_settings.termination_mode | 半角英 | 定期課金の停止リクエストを受理したとき、実際に自動課金のステータスをsupended（一時停止）に変更するタイミング指定可能な値（意味）： immediate（即時）on_next_payment（次回課金日） |
| status | 半角英 | 定期課金のステータスunverified（初回課金の待機中）unconfirmed（初回課金に失敗）canceled（永久停止：リクエストで移行し再開不可）unpaid（リトライ待ち）current（継続中）suspended（一時停止：管理画面で「一時停止」ボタンを押下、リトライ回数の超過、リクエストのいずれかで移行）completed（指定分完了：再開可） |
| metadata | メタデータ ※ CREATE,UPDATE時はネストで任意のフィールドと値を指定可能 | |
| mode | 半角英 | 決済のモードlive（本番）またはtest（テスト） |
| created_on | ISO-8601 | データの作成日時 |
| period | 半角英 | 指定した定期課金の間隔 存在し得る値（意味）： daily（毎日）weekly（毎週）biweekly（隔週）monthly（毎月）bimonthly（隔月）quarterly（3ヶ月）semiannually（6ヶ月）annually（毎年） |
| cyclical_period | ISO8601 duration | 存在し得る値（意味）：PxD（x日周期）PxW（x週間周期）PxM（xヶ月周期）PxY（x年周期）※CREATEで Period未指定なら必須 |
| next_payment.id | UUID | 支払いのID |
| next_payment.due_date | YYYY-MM-DD | 次回課金日 |
| next_payment.zone_id | IANA Timezone | タイムゾーン 例：日本は Asia/Tokyo |
| next_payment.amount | 半角数 | 次回課金額 |
| next_payment.currency | ISO-4217 | 通貨 例：日本円はJPY |
| next_payment.amount_formatted | 半角数 （小数点） | 現実的に流通する補助通貨がある場合、通貨額での課金額 例： correncyがUSDで課金額が110の場合は1.1 |
| next_payment.is_paid | 真偽 | 決済結果（未実行のためfalse固定） |
| next_payment.is_last_payment | 真偽 | 最後の支払いかどうか （回数指定時のみ trueが出力され得る） |
| next_payment.created_on | ISO-8601 | データの作成日時 |
| next_payment.updated_on | ISO-8601 | データの更新日時 |
| next_payment.retry_date | YYYY-MM-DD | 次回課金が失敗した場合のリトライ予定日 |
| three_ds.redirect_id | string (UUID) | リダイレクトリクエストの一意な識別子 リダイレクトURLが正常に指定された場合当システム側で入力されます。 |
| three_ds.redirect_endpoint | string (URL) | 3DS認証後に顧客をリダイレクトするURL 顧客はGET httpメソッドで指定されたエンドポイントにリダイレクトされます。 univapayChargeIdとunivapayTokenIdに加えて、すべてのメタデータ（課金作成時に指定されたもの、作成後に更新されたメタデータは含まない）が自動的にクエリパラメータの一部として送信されます。任意でエンドポイントURLに追加のクエリパラメータを追加することができます。 |
| three_ds.mode | string | 課金の3D-セキュア認証の種類 normal、require、force、skipのいずれかデフォルトでは normalが指定されます。トランザクショントークン作成時に3-Dセキュア認証が完了している場合、3-Dセキュア認証はスキップされ、そうでない場合は3-Dセキュア認証が必要となります。 requireを指定するとトランザクショントークンですでに3-Dセキュア認証が完了していても、3D-セキュア認証を要求します。この時、3-Dセキュアのリスクベース認証によっては本人認証が要求されず決済が完了になる可能性があります。 forceを指定するとトランザクショントークンですでに3-Dセキュア認証が完了していても、強制的に3-Dセキュア認証を行います。この時チャレンジ認証が強制的に行われ、本人認証が必要になります。 skipを指定すると3-Dセキュア認証をスキップします。 これは、消費者が3-Dセキュアを実行できない特定のケースでのみ使用します。 使用するにはアプリトークンのシークレットが必要です。このオプションを有効にするには、サポートにお問い合わせください。 |
