定期課金

定期課金は、定期的に顧客に課金を行うために使用されるコマンドです。定期課金のリクエストを行うためにトランザクショントークンを用いて作成されます。アカウントが審査済みでないと定期課金を作成することはできません。

定期課金は、作成時に指定された間隔で課金を行います。いつでもキャンセル可能です。課金に失敗すると、次の日に再度課金を行い、設定した回数連続で失敗した場合には、定期課金がキャンセルされます。

定期課金が作成されると、即時に課金が作成されます。

ウェブフックを用いて、定期課金イベントの通知を受け取ることを推奨します。 支払いが成功した時はSUBSCRIPTION_PAYMENTイベント、支払いが失敗した時はSUBSCRIPTION_FAILEDイベント、定期課金がキャンセルされた時はSUBSCRIPTION_CANCELEDイベントで通知します。

新しいトランザクショントークンを用いて更新することで定期課金の支払い情報を更新することができます。unpaidの定期課金のトランザクショントークンを更新すると、即時に別の課金を作成します。

The subscription object

Fields
idstring (UUID)
定期課金のユニークID
store_idstring (UUID)
課金が行われたストアのユニークID
amountnumber
課金金額
currencystring (ISO-4217)
課金通貨
amount_formattedstring
補助単位があれば、その小数の値を含む課金のリクエスト金額
initial_amountnumber
初回の課金金額
initial_amount_formattedstring
補助単位があれば、その小数の値を含む初回の課金のリクエスト金額
schedule_settings.start_onstring (ISO-8601)
後続の支払いが開始される日付で、YYYY-MM-DD の形式で指定する。時刻は、zone_id で指定されたタイムゾーンの AM 9:00
schedule_settings.zone_idstring (IANA Timezone)
課金を実行する時刻が基準とするタイムゾーン
schedule_settings.preserve_end_of_monthboolean
period が monthly で、start_on が月末だった場合、課金の実行日を月末に揃えます。例えば、start_on が 2018-06-30 の時、この値が true の場合は次の課金は 2018-07-31 になり、false の場合 2018-07-30 になります
periodstring
課金を行う頻度。
daily（毎日）, weekly（毎週）, biweekly（隔週）, monthly（毎月）, annually（毎年） のいずれか
cyclical_periodstring (ISO-8601 Duration)
課金を行う詳細な頻度、1日間以上で設定します。
このフィールドが入力されている場合、periodは無効になります。
installment_plan.plan_typestring
次のいずれかの値: none, revolving（リボ払い）, fixed_cycles（固定の回数の支払い）

installment_planを指定した定期課金は全てクレジットカード会社による分割になります。
installment_plan.fixed_cyclesnumber
plan_type が fixed_cycles の場合、このフィールドは必須です。カード会社の分割払いの回数を指定します。
支払い回数：3回・5回・6回・10回・12回・15回・18回・20回・24回
※上記以外の回数はエラーになります。
installment_plan.fixed_cycle_amount※5/11に仕様変更がありこのパラメータは利用不可になりました。
subscription_plan.plan_type
string
回数指定の定期課金を行う場合、fixed_cycles, fixed_cycle_amountのいずれか。
subscription_plan.fixed_cycles
number
subscription_plan.plan_type が fixed_cycles の場合、このフィールドは必須です。定期課金を行う回数を指定します。
subscription_plan.fixed_cycle_amount
number
subscription_plan.plan_type が fixed_cycle_amount の場合、このフィールドは必須です。定期課金の1回当たりの支払い金額を指定します。
next_payment.idstring (UUID)
支払いのID
next_payment.due_datestring (ISO-8601)
支払いが実行される日付。時刻は、zone_id で指定されたタイムゾーンの AM 9:00
next_payment.zone_idstring (IANA Timezone)
支払いを実行する時刻が基準とするタイムゾーン
next_payment.amountnumber
課金金額
next_payment.currencystring (ISO-4217)
課金金額の通貨
next_payment.amount_formattedstring
補助単位があれば、小数の値を含む課金金額
next_payment.is_paidboolean
支払いが完了したかどうか
next_payment.is_last_paymentboolean
この支払が定期課金の最後の支払いかどうか。分割払いの場合のみ適用されます
next_payment.created_onstring (ISO-8601)
この支払いの作成日時
payments_leftnumber
分割払の場合、残りの支払回数
amount_leftnumber
分割払いの場合、残りの支払金額
amount_left_formattedstring
分割払いの場合、補助単位があれば、その小数の値を含む、残りの支払い金額
statusstring
定期課金の状態。
unverified（待機中：定期課金を作成し、初回課金の待機中）
unconfirmed（作成失敗：定期課金作成のため初回課金を行うも決済失敗した状態。定期課金として稼働していない状態）
canceled（永久停止：定期課金が完全停止（再開不可）の状態）
unpaid（失敗停止：継続中の定期課金で課金を失敗した状態かつ次の日に再課金待ちの状態。リトライ待ち）
current（継続中：現在稼働中の定期課金）
suspended（一時停止：手動で「一時停止」ボタンを押した状態、または定期課金失敗回数を超えた状態）
completed（完了：指定した課金回数分の決済が終わった状態）
のいずれか
metadatajson
定期課金に紐づいているメタデータ。
定期課金で作成されたメタデータがそれに関連する課金に渡されます。
modestring
liveまたはtest
created_onstring (ISO-8601)
定期課金が作成された日時