---
title: "v.2025-01-28"
description: "In API version v.2025-01-28, we’ve improved how partial captures are represented, expanded the available information on settlements (including a revamped CSV and XLS format), and introduced updates for Platform Model."
date: "2025-01-28"
url: "https://docs.komoju.com/en/changelog/unstable-more-details-in-responses-of-settlements-api-endpoints"
source_url: "https://docs.komoju.com/en/changelog/unstable-more-details-in-responses-of-settlements-api-endpoints.md"
language: en
---

In API version v.2025-01-28, we’ve improved how partial captures are represented, expanded the available information on settlements (including a revamped CSV and XLS format), and introduced updates for Platform Model. Review this changelog for more information on what endpoints have changed.

---

# Updated Endpoints

**Partial Captures improvements:**

1. [GET payments](https://docs.komoju.com/#get-payments)
2. [POST payments](https://docs.komoju.com/#post-payments)
3. [GET payments/:id](https://docs.komoju.com/#get-paymentsid)
4. [PATCH payments/:id](https://docs.komoju.com/#patch-paymentsid)
5. [POST payments/:id/capture](https://docs.komoju.com/#post-paymentsidcapture)
6. [POST payments/:id/refund](https://docs.komoju.com/#post-paymentsidrefund)
7. [POST payments/:id/cancel](https://docs.komoju.com/#post-paymentsidcancel)
8. [POST payments/:id/finalize](https://docs.komoju.com/#post-paymentsidfinalize)
9. [GET merchants/merchant_id/payments](https://docs.komoju.com/#get-merchantsmerchant_idpayments)

**Settlements & Platform Model improvements:**

1. [GET balances/:id](https://docs.komoju.com/#get-balancesid)
2. [GET settlements](https://docs.komoju.com/#get-settlements)
3. [GET settlements/:id](https://docs.komoju.com/#get-settlementsid)
4. [GET settlements/:id/csv](https://docs.komoju.com/#get-settlementsidcsv)
5. [GET settlements/:id/xls](https://docs.komoju.com/#get-settlementsidxls)

# Partial Captures improvements

Partial captures are now represented using a new "captures" array on payment object, instead of being shown as partial refunds, simplifying reporting and reconciliation.

## `GET payments`

The response object for partially captured payments has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: partially captured payments no longer show a refund for the difference between the authorized amount and captured amount.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/GET/payments)

## `POST payments`

The response object for partially captured payments has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: a refund for the difference between the authorized amount and captured amount is not shown if the payment is a partially captured payment.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/POST/payments)

## `GET payments/:id`

The response object for a partially captured payment has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: a refund for the difference between the authorized amount and captured amount is not shown if the payment is a partially captured payment.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/GET/payments/%7Bid%7D)

## `PATCH payments/:id`

The response object for a partially captured payment has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: a refund for the difference between the authorized amount and captured amount is not shown if the payment is a partially captured payment.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/PATCH/payments/%7Bid%7D)

## `POST payments/:id/capture`

The response object for a partially captured payment has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: a refund for the difference between the authorized amount and captured amount is not shown if the payment is a partially captured payment.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/capture)

## `POST payments/:id/refund`

The response object for a partially captured payment has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: a refund for the difference between the authorized amount and captured amount is not shown if the payment is a partially captured payment.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/refund)

## `POST payments/:id/cancel`

The response object for a partially captured payment has been updated.

**Return value changes**:

- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: a refund for the difference between the authorized amount and captured amount is not shown if the payment is a partially captured payment.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/cancel)

## `POST payments/:id/finalize`

The response object for a partially captured payment has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: a refund for the difference between the authorized amount and captured amount is not shown if the payment is a partially captured payment.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/payments/POST/payments/%7Bid%7D/finalize)

## `GET merchants/:merchant_id/payments`

The response object for a partially captured payment has been updated.

- **Return value changes**:
- `amount_refunded`: the refund amount for the difference between the authorized amount and captured amount is no longer included for partially captured payments.
- `refunds`: partially captured payments no longer show a refund for the difference between the authorized amount and captured amount.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/platform-model/GET/merchants/%7Bmerchant_id%7D/payments)

# Settlements & Platform Model improvements

We updated endpoint structures to support the new [Platform Model](https://docs.komoju.com/en/docs/platform-model/platform-model-overview.md), and expanded the available keys to include more settlement data. The formats of the CSV and XLS settlement reports have been changed to include this new data as well.

## `GET balances/:id`

Transformed the response to a nested (2D) structure to match the Merchant dashboard's Payout Balance page.

- **Renamed keys**:
- `balance_total` is now `total_balance_cents`.
- **Removed keys**:
- `payment_fee_total`, `tax_total`.
- **Structural changes**:
- Added new `payments`, `refunds`, `platform_model`, `corrections`, `komoju_card_charges` and `misc` sections.
- `payments`:
- Moved here: `payment_total` now called `captured_amount_total`
- New keys: `processing_fees`
- `refunds`:
- Moved here:
- `refund_total` now called `refunded_amount_total_cents`
- `refund_fee_total` now called `refund_processing_fees_cents` and includes tax
- `refunded_customer_fee_total` now called `refunded_customer_fees_cents` and includes tax
- `platform_model` (only available for Platform merchants):
- Moved here: `fund_transfer_total_cents`
- New keys: `payment_share_total_cents`, `payment_share_refund_total_cents`, `platform_fee_total_cents`, `platform_fee_refund_total_cents`, `submerchant_management_fees_cents`.
- `disbursements`:
- New keys: `disbursement_amount_total_cents`, `disbursement_fee_total_cents`.
- `misc`:
- New keys: `clearing_total_cents`, `komoju_card_discount_total_cents`, `chargeback_fixed_fee_total_cents`, `other_fee_adjustments_total_cents` (this is the sum of all fee adjustments and any misc. record types that don't belong in other sections. Refer to the API reference for the exhaustive list).
- For each section, added a `total_cents` of each of its amounts.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/settlements/GET/balances/%7Bcurrency%7D)

## `GET settlements`

Renamed one key name, added a number of new keys, and made changes to several returned values.

- **Renamed keys**:


- `amount` is now `settlement_amount_cents` in order to make the key more clear and less generic.
- **Added keys**:


- NOTE: values for keys ending in `_cents` are returned as integers (not strings); any integers related to fees can be negative integers.
- `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`
- **Return value changes**:


- `status`: "automatic_pending" is now returned as "pending".
- `settlement_amount_cents` (formerly `amount`): the value of `settlement_amount_cents` is now returned as an integer rather than a string.
- `download`: all keys in this section (such as `csv` or `xls`) will show "null" instead of a link if the settlement is cancelled. If the settlement is not cancelled, all links will point to an updated version of the report.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/settlements/GET/settlements)

## `GET settlements/:id`

Renamed two key names, added a number of new keys, made changes to several returned values, and transformed the response to a nested (2D) structure to include details for various kinds of payments and fees.

- **Renamed keys**:


- `amount` is now `settlement_amount_cents` in order to make the key more clear and less generic.
- **Removed keys**:


- `payment_total`
- `payment_fee_total`
- `refund_total`
- `refund_fee_total`
- `refunded_customer_fee_total`
- `correction_total`
- `tax_total`
- `balance_amount`
- **Added keys**:


- NOTE: values for keys ending in `_cents` are returned as integers (not strings); any integers related to fees can be negative integers.
- `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` (for platform merchants only)
- `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` (for platform merchants only)
- `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` - this is the sum of all fee adjustments and any misc. record types that don't belong in other sections. Refer to the API reference for the exhaustive list.
- `total_cents`
- **Return value changes**:


- `download`: all keys in this section (such as `csv` or `xls`) will show "null" instead of a link if the settlement is cancelled. If the settlement is not cancelled, all links will point to an updated version of the report.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/settlements/GET/settlements/%7Bid%7D)

## `GET settlements/:id/csv`

Updated format of the report.

- **Return value changes**:
- The format of the returned report has been updated.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/settlements/GET/settlements/%7Bid%7D/csv)

## `GET settlements/:id/xls`

Updated format of the report.

- **Return value changes**:
- The format of the returned report has been updated.

[Full API Reference for this endpoint](https://docs.komoju.com/en/api-reference#2025-01-28/tag/settlements/GET/settlements/%7Bid%7D/xls)