Settlement report types

Learn about the Settlement report formats available through the Klarna API and SFTP, including JSON, CSV, and PDF reports for reconciliation, accounting, and tax compliance.

54 min read

Klarna provides Settlement data in three formats — JSON, CSV, and PDF — delivered through the API and SFTP, so Acquiring Partners can choose the report type that best fits their reconciliation, accounting, and tax compliance needs.

When Klarna processes a Settlement, it generates reports that break down captures, fees, refunds, chargebacks, and other adjustments. These reports are available through two channels: the Settlements API (on-demand retrieval) and SFTP (automatic upload by Klarna). Each format serves a different purpose — from programmatic reconciliation to human-readable tax documentation.

Report delivery channels

Settlement reports reach Acquiring Partners through two channels:

API: Retrieve reports on demand in any format (JSON, CSV, or PDF). Use the API when your system needs to pull Settlement data programmatically or when you need a specific report for a single Settlement.
SFTP: Klarna automatically uploads CSV and PDF reports to your SFTP server after each Settlement is processed. The CSV format uploaded to SFTP is configured per Acquiring Partner by Klarna. JSON reports aren't available through SFTP. SFTP is the preferable channel for large reports — although the API streams the response, the download speed depends on the connection between your system and Klarna, and your system's capability to ingest large amounts of data.

SFTP setup reference

For SFTP setup, file name conventions, and server connection details, see Settlement Reports.

Settlement report webhooks

Klarna dispatches webhooks to notify you when reports are ready, so you don't need to poll the API.

Event name	When it fires	What to do
`settlement.report.created`	The Settlement report is available on the API in all formats	Fetch the report using the API
`settlement.report.uploaded-to-sftp`	The Settlement report CSV has been uploaded to your SFTP server	Retrieve the file from SFTP

The settlement.report.created webhook includes links to the reports, so you can retrieve them directly without looking up the settlement_id first.

sequenceDiagram autonumber participant P as Acquiring Partner participant K as Klarna participant S as Klarna SFTP K->>K: Process Settlement K->>K: Generate reports (JSON, CSV, PDF) K->>P: settlement.report.created K->>S: Upload CSV and PDF K->>P: settlement.report.uploaded-to-sftp P->>K: Retrieve report via API (JSON, CSV, or PDF) P->>S: Retrieve CSV or PDF from SFTP

Available report types

Report	Format	Endpoint	Delivery channels	Content
Settlement details	JSON	getSettlement	API	Settlement totals and metadata
Settlement transactions	JSON	getTransactionsBySettlementId	API	Individual transactions with pagination
Combined report	CSV	getSettlementCsv	API, SFTP	Summary + transactions in one file
Summary report	CSV	getSettlementSummaryReport	API	Settlement totals — one header row, one data row
Transactions report	CSV	getSettlementTransactionsReport	API	All transactions — one row per transaction (streamed)
Tax invoice	PDF	getSettlementTaxInvoice	API, SFTP	Tax documentation with Settlement breakdown

Settlement details (JSON)

The JSON endpoints give you programmatic access to Settlement data with structured objects and cursor-based pagination.

Get Settlement summary

Use getSettlement API

to retrieve the totals for a specific Settlement. The response includes the Settlement amount, currency, period, and a totals object with 15 fields covering captures, refunds, fees, chargebacks, tax, holdbacks, releases, and debt balances.

List Settlement transactions

Use getTransactionsBySettlementId API

to retrieve individual transactions for a Settlement. The response uses cursor-based pagination — pass size, starting_after, or ending_before to page through results.

Each transaction is polymorphic, meaning its structure varies by type. See Transaction types reference for the full breakdown.

Settlement CSV reports

Klarna offers three CSV report variants. The combined report is a legacy format that merges summary and transaction data into a single file that isn't strictly CSV-compliant. For standard CSV processing, use the separate summary and transactions endpoints instead.

Combined report

The getSettlementCsv API

endpoint returns a single CSV file containing both the Settlement summary and individual transactions.

Recommended for integration

This report is not strictly CSV-compliant because it combines two different CSV layouts in one file. The first section has a header row and one data row with Settlement totals. The second section has a separate header row and one row per transaction. If your CSV parser expects a single header row, use the separate summary and transactions endpoints instead.

Column reference

Summary section columns: settlement_id, payment_acquiring_account_id, payment_acquiring_account_reference, created_at, period_from, period_to, settlement_amount, currency, capture_amount, refund_amount, capture_fixed_fee_amount, capture_variable_fee_amount, dispute_fee_amount, fee_correction_amount, chargeback_amount, correction_chargeback_amount, tax_amount, holdback_amount, release_amount, opening_debt_balance, deposit_amount, repay_amount, closing_debt_balance, paid_out_at, payout_bank_account_reference, payment_reference, settlement_account_id, settlement_account_reference

Info

Klarna enables the updated settlement report that carries chargeback reversals per Acquiring Partner — the report format required before the ON_DISPUTE_INITIATED dispute hold policy can be turned on. See Disputes and chargebacks in the settlement report.

Once it is enabled, the correction_chargeback_amount column is renamed to chargeback_reversal_amount and carries the reversal total. It keeps its position, so the column count and order are unchanged. In JSON, chargeback_reversal_amount is omitted until then; after that it is present and correction_chargeback_amount is kept, deprecated, and reads 0.

Transaction section columns: type, detailed_type, created_at, amount, currency, transaction_event_amount, transaction_event_currency, exchange_rate, payment_account_id, payment_account_reference, product_id, payment_transaction_id, payment_transaction_created_at, payment_transaction_reference, payment_capture_id, payment_capture_reference, payment_refund_id, payment_refund_reference, payment_dispute_id, payment_chargeback_id, tax_amount, tax_rate, applied_transaction_fee, applied_cross_border_fee, applied_buy_rate_incentives, applied_sell_rate_incentives, price_plan_id, payment_program_id, merchant_category_code, store_id, store_reference

Summary report

The getSettlementSummaryReport API

endpoint returns a standard CSV with one header row and one data row containing Settlement totals and payout details.

The columns are the same as the summary section columns in the combined report.

Transactions report

The getSettlementTransactionsReport API

endpoint returns a standard CSV with one header row and one row per transaction. This report is streamed, so it can handle very large Settlements. The columns are the same as the transaction section columns in the combined report, with the addition of a settlement_id column.

CSV formatting conventions

These conventions apply to all CSV endpoints:

Delimiter: Comma (,)
Amounts: Minor currency units — $1.00 is represented as 100
Amount signs: Positive values are credits, negative values are debits
Percentages: Integer in minor units — 15.57% is represented as 1557

Integration requirement

New columns may be added at the end of the CSV without notice. This isn't a breaking change. Don't hard-code the number of columns in your parser — always handle additional columns gracefully.

Recommended for integration

Quoting with double quotes may apply to all fields or only to fields that require it (fields containing a delimiter or newline). Your parser should handle both quoted and unquoted values.

Tax invoice (PDF)

The getSettlementTaxInvoice API

endpoint returns a PDF document that breaks down Settlement amounts — sales, fees, taxes, refunds, chargebacks, and more. It can be used as supporting documentation for:

VAT invoices in the EU
Tax invoices in AU/NZ

Recommended for integration

The tax invoice includes a transaction list with a maximum of 2,500 transactions. For Settlements with more transactions, use the JSON or CSV endpoints for full transaction-level data. The PDF file size is capped at 5 MB.

Transaction types reference

Settlement transactions are polymorphic — each transaction has a type that determines which detailed_type values and fields are populated. All amounts follow the same sign convention: positive values are credits to the Acquiring Partner, negative values are debits.

Type	Detailed types	Amount sign	Description
`SALE`	`CAPTURE`	Positive	A captured payment amount credited to the Acquiring Partner
`FEE`	`CAPTURE_FIXED_FEE`, `CAPTURE_VARIABLE_FEE`, `DISPUTE_FEE`, `APPEAL_FEE`	Negative	Fees charged by Klarna for captures and disputes
`REFUND`	`REFUND`	Negative	A refund issued to the customer, debited from the Acquiring Partner
`CHARGEBACK`	`CHARGEBACK`, `CUSTOMER_CURRENCY_CONVERSION_DELTA`, `CUSTOMER_PAYMENT_DEFAULT`, `CORRECTION_CHARGEBACK` (deprecated)	Usually negative	Reversal of a transaction following a dispute. With the hold policy (`ON_DISPUTE_INITIATED`) enabled, `CHARGEBACK` is raised when the dispute is initiated rather than when it is lost
`CHARGEBACK_REVERSAL`	`CHARGEBACK_REVERSAL`, `CUSTOMER_CURRENCY_CONVERSION_DELTA`	Positive	Returns a previously charged-back amount to the Acquiring Partner. `CHARGEBACK_REVERSAL` covers both a dispute won by the Acquiring Partner and a chargeback Klarna raised in error and later corrected, replacing the deprecated `CHARGEBACK / CORRECTION_CHARGEBACK`
`FEE_CORRECTION`	`CORRECTION_CAPTURE_FIXED_FEE`, `CORRECTION_CAPTURE_VARIABLE_FEE`, `CORRECTION_DISPUTE_FEE`, `CORRECTION_APPEAL_FEE`	Positive	Corrects a previously charged fee — credits the Acquiring Partner
`HOLDBACK`	`INSUFFICIENT_BANK_ACCOUNT_DETAILS`, `UNDER_REVIEW`	Negative	Funds held back due to account issues
`RELEASE`	`INSUFFICIENT_BANK_ACCOUNT_DETAILS`, `UNDER_REVIEW`	Positive	Previously held funds released to the Acquiring Partner

Settlement Reports

Disputes and chargebacks in the settlement report

Jump to section...