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
2. POST payments
3. GET payments/:id
4. PATCH payments/:id
5. POST payments/:id/capture
6. POST payments/:id/refund
7. POST payments/:id/cancel
8. POST payments/:id/finalize
9. GET merchants/merchant_id/payments

Settlements & Platform Model improvements:

1. GET balances/:id
2. GET settlements
3. GET settlements/:id
4. GET settlements/:id/csv
5. GET settlements/:id/xls

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

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

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

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

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

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

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

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

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

Settlements & Platform Model improvements

We updated endpoint structures to support the new Platform Model, 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

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

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

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

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