旧 /api/v1/checkin/ API は、新規での提供を停止しています。 このヘルプは、既に API 利用されているベンダー向けのものです。
仕様書：
payment_status の仕様について
API v1では、予約が一部入金（Partial Payment）状態であるかどうかは判定できますが、
実際にいくら支払い済みなのか
あといくら徴収する必要があるのか
いくら返金すべきなのか
を正確に判定することはできません。
これは、API v1提供当時は「宿泊費はOTA支払い」または「現地で全額精算」の運用を前提として設計されていたためです。
GET /api/v1/bookings では、
payment_statusfeesbooking_fees
などの料金情報は取得できますが、
以下のようなトランザクションレベルの支払い情報は取得できません。
支払い済み金額
未払い残高
支払い履歴
返金履歴
また、fees / booking_fees には料金項目が含まれていますが、予約内容や支払い情報が管理画面から手動変更されている場合は、これらの情報だけを基に支払済み金額や未払い金額を正確に計算することはできません。
実装可能な精算パターン
API v1では、以下のような実装を推奨します。
payment_status | 実装方法 |
| 精算不要 |
| 全額請求 |
| APIでは精算金額を判定できないため施設による手動フォロー |
| APIでは過払い金額を判定できないため施設による手動フォロー |
チェックイン端末での請求額判定方法
payment_status = paid
精算不要
請求額：0円
payment_status = not_paid
予約内の料金項目をそのまま請求します。
請求額
fees[] または booking_fees[] の合計
ご注意
請求額を計算する際は、
included == false
の料金項目のみを合計してください。
included == true は「宿泊料金に既に含まれている料金」であることを示します。
これらまで合計してしまうと、宿泊費に含まれている金額を再度請求してしまうため、二重請求となります。
また、各料金項目に存在する paid フラグは、チェックイン時の請求判定には使用しないでください。
payment_status = partial_paid
APIでは
いくら支払い済みなのか
あといくら請求すべきか
を判定できません。
そのため、
チェックイン端末では請求処理を行わない
施設側で手動対応
を行ってください。
payment_status = over_paid
APIでは
過払い金額
返金額
を判定できません。
そのため、
チェックイン端末では請求処理を行わない
施設側で手動対応
を行ってください。
partial_paid / over_paid が発生するケース
over_paid
通常運用ではほとんど発生しません。
管理画面（PMS）で誤って請求額以上の入金を登録した場合などに発生します。
partial_paid
代表的なケースは、
OTAで宿泊料金を支払い済みの予約に対して追加請求を登録した場合
です。
例えば、
宿泊税
入湯税
駐車料金
オプション料金
などを後から追加請求した場合、
payment_status = partial_paid
となります。
この場合でもAPI v1では、
宿泊費はいくら支払い済みか
追加料金だけ未払いなのか
一部だけ支払われているのか
を正確に判定できないため、チェックイン端末で自動精算を行うことはできません。
施設側で金額を確認し、手動で対応してください。
まとめ
API v1では精算処理を安全に行えるのは以下の2パターンのみです。
payment_status = paid→ 請求なしpayment_status = not_paid→ 全額請求
partial_paid および over_paid はトランザクション情報が取得できないため、自動精算は行わず、施設による手動対応を前提として実装してください。