APIバージョン v.2025-01-28 では、部分入金の表現方法を改善し、決済に関する情報を拡張しました（CSVおよびXLS形式を刷新しました）。また、プラットフォームモデルのアップデートを導入しました。どのエンドポイントが変更されたかの詳細は、変更履歴をご確認ください。

アップデートされたエンドポイント

部分入金に関する改善点:

GET payments
POST payments
GET payments/:id
PATCH payments/:id
POST payments/:id/capture
POST payments/:id/refund
POST payments/:id/cancel
POST payments/:id/finalize
GET merchants/merchant_id/payments

決済とプラットフォームモデルの改善点：

GET balances/:id
GET settlements
GET settlements/:id
GET settlements/:id/csv
GET settlements/:id/xls

部分入金に関する改善点

部分入金は、部分的な払い戻しとしてではなく、決済オブジェクトの新しい「入金」配列を使用して表現されるようになり、レポート作成と照合が簡素化されました。

`GET payments`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 部分入金の場合、承認金額と入金金額の差額に対する返金は表示されなくなりました。

このエンドポイントのAPIリファレンス

`POST payments`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 支払いが部分入金の場合、承認金額と入金金額の差額に対する返金は表示されません。

このエンドポイントのAPIリファレンス

`GET payments/:id`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 支払いが部分入金の場合、承認金額と入金金額の差額に対する返金は表示されません。

このエンドポイントのAPIリファレンス

`PATCH payments/:id`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 支払いが部分入金の場合、承認金額と入金金額の差額に対する返金は表示されません。

このエンドポイントのAPIリファレンス

`POST payments/:id/capture`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 支払いが部分入金の場合、承認金額と入金金額の差額に対する返金は表示されません。

このエンドポイントのAPIリファレンス

`POST payments/:id/refund`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 支払いが部分入金の場合、承認金額と入金金額の差額に対する返金は表示されません。

このエンドポイントのAPIリファレンス

`POST payments/:id/cancel`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded:部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 支払いが部分入金の場合、承認金額と入金金額の差額に対する返金は表示されません。

このエンドポイントのAPIリファレンス

`POST payments/:id/finalize`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました
- refunds: 支払いが部分入金の場合、承認金額と入金金額の差額に対する返金は表示されません。

このエンドポイントのAPIリファレンス

`GET merchants/:merchant_id/payments`

部分入金のレスポンスオブジェクトが更新されました。

戻り値の変更点:
- amount_refunded: 部分入金の場合、承認金額と入金金額の差額に対する返金額は含まれなくなりました。
- refunds: 部分入金の場合、承認金額と入金金額の差額に対する返金は表示されなくなりました。

このエンドポイントのAPIリファレンス

決済とプラットフォームモデルの改善点

新しいプラットフォームモデルをサポートするためにエンドポイント構造を更新し、決済データを含めるために利用可能なキーを拡張しました。CSVおよびXLS決済レポートの形式も、この新しいデータを含めるように変更されました。

`GET balances/:id`

マーチャントダッシュボードの未精算残高ページに合わせて、レスポンスをネストされた（2次元）構造に変換しました。

キーの名前を変更しました:
- balance_total はtotal_balance_centsになりました。
削除されたキー:
- payment_fee_total, tax_total。
構造の変更点:
- payments, refunds, platform_model, corrections, komoju_card_charges およびmisc のセクションを新しく追加しました。
  - payments:
    - 移動されました: payment_total はcaptured_amount_totalになりました。
    - 新しいキー：processing_fees
  - refunds:
    - 移動されました:
      - refund_total はrefunded_amount_total_centsになりました。
      - refund_fee_total は refund_processing_fees_cents になり、税金が含まれます。
      - refunded_customer_fee_total は refunded_customer_fees_centr になり、税金が含まれます。
  - platform_model (プラットフォーム加盟店のみ):
    - 移動されました： fund_transfer_total_cents
    - 新しいキー： payment_share_total_cents, payment_share_refund_total_cents, platform_fee_total_cents, platform_fee_refund_total_cents, submerchant_management_fees_cents.
  - disbursements:
    - 新しいキー： disbursement_amount_total_cents, disbursement_fee_total_cents.
  - misc:
    - 新しいキー clearing_total_cents, komoju_card_discount_total_cents, chargeback_fixed_fee_total_cents, other_fee_adjustments_total_cents (これは、すべての手数料調整と、他のセクションに属さないその他の記録タイプの合計です。詳しいリストについては、APIリファレンスを参照してください）。
  - 各セクションに、各金額のtotal_cents を追加しました。

このエンドポイントのAPIリファレンス

`GET settlements`

キーの名前を1つ変更し、いくつかの新しいキーを追加し、いくつかの戻り値を変更しました。

キーの名前を変更しました:
- amount はキーをより明確かつ汎用性の低いものにするためにsettlement_amount_cents になりました。
追加されたキー:
- 注意： _cents で終わるキーの値は整数（文字列ではない）として返されます。手数料に関連する整数は負の整数になる場合があります。
- transaction_amount_cents
- fee_amount_cents
- fee_tax_amount_cents
- fx_currency
- fx_conversion_rate
- fx_conversion_amount_cents
- bank_transfer_fee_amount_cents
- remittance_amount_cents
戻り値の変更点:
- status: "automatic_pending" は "pending" として返されるようになりました。
- settlement_amount_cents (以前は amount): settlement_amount_cents の値は、文字列ではなく整数として返されるようになりました。
- download: このセクションのすべてのキー (csv や xlsなど) は、決済がキャンセルされた場合、リンクの代わりに "null" を表示します。決済がキャンセルされていない場合、すべてのリンクは更新されたバージョンのレポートを指します。

このエンドポイントのAPIリファレンス

`GET settlements/:id`

キーの名前を2つ変更し、いくつかの新しいキーを追加し、いくつかの戻り値を変更し、さまざまな種類の支払いと手数料の詳細を含めるために、レスポンスをネストされた（2次元）構造に変換しました。

キーの名前を変更しました:
- amount はキーをより明確かつ汎用性の低いものにするために settlement_amount_cents になりました。
削除されたキー：:
- payment_total
- payment_fee_total
- refund_total
- refund_fee_total
- refunded_customer_fee_total
- correction_total
- tax_total
- balance_amount
追加されたキー:
- 注意：_cents で終わるキーの値は整数（文字列ではない）として返されます。手数料に関連する整数は負の整数になる場合があります。
- transaction_amount_cents
- fee_amount_cents
- fee_tax_amount_cents
- fx_currency
- fx_conversion_rate
- fx_conversion_amount_cents
- bank_transfer_fee_amount_cents
- remittance_amount_cents
- payments
  - captured_amount_total_cents
  - processing_fees_cents
  - total_cents
- refunds
  - refunded_amount_total_cents
  - refund_processing_fees_cents
  - refunded_customer_fees_cents
  - total_cents
- platform_model (プラットフォーム加盟店のみ)
  - fund_transfer_total_cents
  - payment_share_total_cents
  - payment_share_refund_total_cents
  - platform_fee_total_cents
  - platform_fee_refund_total_cents
  - submerchant_management_fees_cents (プラットフォーム加盟店のみ)
  - total_cents
- corrections
  - total_cents
- komoju_card_charges
  - total_cents
- disbursements
  - disbursement_amount_total_cents
  - disbursement_fee_total_cents
  - total_cents
- misc
  - clearing_total_cents
  - komoju_card_discount_total_cents
  - chargeback_fixed_fee_total_cents
  - other_fee_adjustments_total_cents - これは、すべての手数料調整と、他のセクションに属さないその他の記録タイプの合計です。詳しいリストについては、APIリファレンスを参照してください。
  - total_cents
戻り値の変更点:
- download: このセクションのすべてのキー (csvまたはxls\) は、決済がキャンセルされた場合、リンクの代わりに "null" を表示します。決済がキャンセルされていない場合、すべてのリンクは更新されたバージョンのレポートを指します。

このエンドポイントのAPIリファレンス

`GET settlements/:id/csv`

レポートの形式を更新しました。

戻り値の変更点:
- 返されるレポートの形式が更新されました。

このエンドポイントのAPIリファレンス

`GET settlements/:id/xls`

レポートの形式を更新しました。

戻り値の変更点:
- 返されるレポートの形式が更新されました。

このエンドポイントのAPIリファレンス

Changelog

v.2026-01-27

v.2025-01-28

APIバージョン管理の導入