定期課金 – 概要
定期課金とは、本サービスにより定期的かつ自動的に課金することを指します。
オブジェクト名は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 | 次回課金が失敗した場合のリトライ予定日 |
