決済方法登録変更API

概要

決済方法の登録・変更をするAPIです。

支払方法・支払タイミング・プランを一挙に登録・更新します。

エンドポイント

メソッド URI Headers
POST /api/payment/method Default

リクエストパラメーター

パラメーター名 型 内容 特記
payment_method tinyint 1：クレジット　 5：コンビニ払い
plan int プラン人数 2021.09.08段階最低5人以上
payment_timing tinyint 1：年払い 5：月払い
credit_card_number string カード番号 GMO JSのgetTokenメソッドにて取得した、間に*でマスク入っているカード番号
cvs_code varchar 支払先コンビニエンスコード ※GMO PAYMENTの支払先コンビニエンスコードがどんな値なのか不明なので確認後変更の可能性あり 
{
    'payment_method'     : 1,
    'plan'               : 10,
    'payment_timing'     : 5,
    'credit_card_number' : '41111********111',
    'cvs_code'           : '10001',
}

※ クレジットカード情報はクレジットカード登録モーダルで登録済みなので、支払方法にてクレジットカードを選択しているが、実際クレジットカードを決済APIに登録しているか確認するため、マスクしたクレジットカード番号をリクエストパラメータに含めています。

レスポンス

成功時
パラメーター名 型 内容 特記
result boolean リクエスト結果
is_initial boolean 初回の支払設定登録か？
true：初回
false：初回以外		 初回の支払設定登録の場合は、当月支払画面へリダイレクトします。 
{
    "result"   : true,
    "data"     : {
        "is_initial" : true
    },
}
失敗時

ステータスコード：200

パラメーター名 型 内容 特記
result boolean リクエスト結果
payment_method string not null / int
plan string not null / int / 5人以上
payment_timing string not null / int
credit_card_type string not null / int
credit_card_number string not null / int
credit_card_nominee string not null / string
credit_card_effective string not null / date @tododateformatになる可能性あり 
{
  "result"   : false,
  "errors"   : {
    'payment_method'           : '必須項目です|数値で入力してください',
    'plan'                     : '必須項目です|数値で入力してください',
    'payment_timing'           : '必須項目です|数値で入力してください',
  },
  "data"     : "",
}

{primary} 本機能で取得するデータに対してのvalidationを明記します

バリデーション

画面項目名 フィールド名 チェック内容 備考
支払方法 payment_method required


numeric


・支払方法に「1：クレジットカード払い」を選択している場合はcredit_card_numberの値がリクエストパラメータに含まれるか？
・支払方法に「5：コンビニ払い」を選択している場合はcvs_codeの値が選択されているか？
プラン人数 plan required


numeric
支払時期 payment_timing required


numeric

データストア

organization_payment_settings

  • 支払方法がクレカ or コンビニのときに登録する項目に〇を記載しています。
物理名 フィールド名 型 クレカ コンビニ 備考
監理団体ID organization_id int 〇 〇 ログインしている監理団体のIDを登録します。
決済API上の会員ID api_member_id int 〇
支払方法 payment_method tinyint 〇 〇 1:クレジット, 5:コンビニ払い
プラン人数 plan int 〇 〇
支払時期 payment_timing tinyint 〇 〇 1：年払い 5：月払い
カード種類 credit_card_type tinyint 〇 1：VISA　5：MASTER　10：JCB
15：AMEX　20：DINERS
カード下四桁 credit_card_number integer 〇 カード下四桁
カード名義人 credit_card_nominee string 〇 カード名義人
カード有効期限 月 credit_card_effective_month tinyint 〇 カード有効期限 月
カード有効期限 年 credit_card_effective_year tinyint 〇 カード有効期限 年
支払先コンビニエンスコード cvs_code varchar 〇 @todo コンビニエンスコードが分かったらコードについて追記します。
基本料金単価 basic_charge_unit_price int ※ ※ 新規登録時のみ、application_informationに登録されている基本料金単価を取得して登録します。
従量課金単価 pay_per_use_price int ※ ※ 新規登録時のみ、application_informationに登録されている基本料金単価を取得して登録します。

organization_payments

論理名 物理名 型 備考
監理団体ID organization_id int ログインしている監理団体のIDを登録します。
監理団体　支払設定ID organization_payment_setting_id int ログインしている監理団体の支払設定のIDを登録します。
支払年 payment_year int 新規登録時は当月の年を登録します。編集時は値を変更しません。
支払月 payment_month int 新規登録時は当月の月を登録します。編集時は値を変更しません。
請求対象期間　開始 billing_period_from date 新規登録時は本日を登録します。編集時は値の変更はしません。
請求対象期間　終了 billing_period_until date 新規登録時は当月の末日を登録します。編集時は値の変更はしません。
支払方法 payment_method tinyint 画面で選択した支払方法を登録します。
支払時期 payment_timing tinyint 画面で選択した支払時期を登録します。
請求種類 payment_type tinyint 新規登録時は「2：初月」で登録します。編集時は値の変更はしません。
プラン人数 plan int 画面で入力されたプライン人数を登録します。
基本料金単価 basic_charge_unit_price int 新規登録時は支払設定organization_payment_settingsに登録されている基本料金単価を登録します。
従量課金単価 pay_per_use_price int 新規登録時は支払設定organization_payment_settingsに登録されている従量課金単価を登録します。
請求　小計 subtotal_amount int PaymentAmountクラスにて計算した請求小計を登録します。
請求　消費税 tax int PaymentAmountクラスにて計算した請求消費税を登録します。
請求　合計 total_amount int PaymentAmountクラスにて計算した請求合計を登録します。
請求明細 payment_details json PaymentAmountクラスにて作成される明細を登録します。
この請求データで基本料金年払いをするか？ is_annual_payment boolean PaymentAmountクラスにて今回基本料金年払いを行うかの判定を行い、その値を登録します。
請求　合計　初期値 total_amount_init int 新規登録時は請求合計と同じ値を登録します。編集の時は値を変更しません。
カード番号 credit_card_number varchar 支払方法でクレジットカード払いが選択されている場合のみ、間を＊でマスクしたクレジットカード番号を登録します。
請求確定日時 billing_confirmed_at datetime 新規登録時は現在日時を登録します。編集時は支払時期が変更されたときのみ現在日時で更新します。
取引登録回数 trade_regist_count int コンビニ決済時のみ、取引登録を行う度、カウント値を増やしていきます。
請求状態 status tinyint 新規登録時は「1：未入金」を登録します。編集時は値の変更はしません。

処理の流れ

{primary} このAPIでは新規登録か編集か、また支払方法がクレジットカード払いかコンビニ払いかで処理の流れがことなるためここに処理の流れを記載しています。

ここに記載するのはバリデーション通過後の処理の流れです。

クレジットカード払いの場合

新規登録時

  1. 監理団体 支払設定organization_payment_settingsに画面で入力した値と、クレジットカード情報登録時に作成された支払設定一時保存temp_payment_settingsの内容を登録します。

  2. 監理団体 請求データorganization_paymentsに初月払いの請求データを作成します。

  3. レスポンスis_initial = trueを返し、このレスポンスを受け取ったJSにて当月費用支払い画面へリダイレクトさせます。

編集時
  1. 更新対象の監理団体 支払設定organization_payment_settingに画面で入力した値を登録します。※編集時はこのAPIではクレジットカード情報の登録・更新は行いません。クレジットカード情報登録APIにて行います。

  2. 請求種類（毎月・初月・アカウント停止）問わず、未払いの請求データorganization_paymentsが存在する場合は下記の場合、請求金額の再計算を行い、各金額と明細を更新します。

    • 支払時期を「年払い」→「月払い」へ変更
    • 支払時期を「月払い」→「年払い」へ変更

コンビニ払いの場合

新規登録時

  1. 監理団体 支払設定organization_payment_settingsに画面で入力した値を登録します。

  2. 監理団体 請求データorganization_pyamentsに初月払いの請求データを作成します。

  3. 決済APIに初月払いの取引登録を行います。

  4. 決済APIに決済要求します。（GMOコンビニ決済資料では「決済実行」と表記されています。）

  5. 決済APIに決済要求した際のレスポンスを2.で作成した監理団体 請求データorganization_paymentsに登録します。

  6. レスポンスis_initial = trueを返し、このレスポンスを受け取ったJSにて当月費用支払い画面へリダイレクトさせます。

更新時

  1. 更新対象の監理団体 支払設定organization_payment_settingに画面で入力した値を登録します。

  2. 請求種類（毎月・初月・アカウント停止）問わず、未払いの請求データorganization_paymentsが存在する場合は下記の場合、請求金額の再計算を行い、各金額と明細を更新します。

  3. 決済APIに既に登録されている取引を取消します。

  4. 決済APIに新たな取引登録を行います。

  5. 決済APIに決済要求します。（GMOコンビニ決済資料では「決済実行」と表記されています。）

  6. 決済APIに決済要求した際のレスポンスを2.で作成した監理団体 請求データorganization_paymentsに登録します。

  7. 初月払いの場合はレスポンスis_initial = trueを返し、このレスポンスを受け取ったJSにて当月費用支払い画面へリダイレクトさせます。初月払い以外の場合はレスポンスis_initial = falseを返し、当月費用支払い画面へはリダイレクトさせないようにします。

※未払いの請求データ取得条件
未払いの請求データ取得条件項目 値 テーブル.カラム
監理団体 支払設定ID 対象監理団体の支払設定ID organization_pyaments.organization_payment_setting_id
支払年月が今月 今月の年月 organization_pyaments.payment_year & payment_month
請求状態 未入金 organization_pyaments.payment_status
請求データクローズフラグ false organization_pyaments.closed

RUN