Settlement report types

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

Klarna provides settlement data in three formats (JSON, CSV, and PDF) delivered through the API and SFTP, so Partners can choose the report type that best fits 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 Partners through two channels:

API: retrieve reports on demand in any format (JSON, CSV, or PDF). Use the API when the Partner's system pulls settlement data programmatically, or when a specific report for a single settlement is needed.
SFTP: Klarna automatically uploads CSV and PDF reports to the Partner's SFTP server after each settlement is processed. The CSV format uploaded to SFTP is configured per Partner by Klarna. JSON reports are not 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 the Partner's system and Klarna, and on the Partner's capability to ingest large amounts of data.

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

Settlement report webhooks

Klarna dispatches webhooks to notify Partners when reports are ready, removing the 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 the Partner's SFTP server.	Retrieve the file from SFTP.

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

sequenceDiagram autonumber participant P as 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 through the 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 and 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 provide 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 is not 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.

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. When the Partner's 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.

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.

New columns may be added at the end of the CSV without notice. This is not a breaking change. Do not hard-code the number of columns in the parser. Always handle additional columns gracefully.

Quoting with double quotes may apply to all fields, or only to fields that require it (fields containing a delimiter or newline). The Partner's 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.

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 Partner, negative values are debits.

Type	Detailed types	Amount sign	Description
`SALE`	`CAPTURE`	Positive	A captured payment amount credited to the Partner.
`FEE`	`CAPTURE_FIXED_FEE`, `CAPTURE_VARIABLE_FEE`, `DISPUTE_FEE`	Negative	Fees charged by Klarna for captures and disputes.
`REFUND`	`REFUND`	Negative	A refund issued to the customer, debited from the Partner.
`CHARGEBACK`	`CHARGEBACK`, `CUSTOMER_CURRENCY_CONVERSION_DELTA`, `CUSTOMER_PAYMENT_DEFAULT`, `CORRECTION_CHARGEBACK`	Usually negative	Reversal of a transaction following a dispute.
`FEE_CORRECTION`	`CORRECTION_CAPTURE_FIXED_FEE`, `CORRECTION_CAPTURE_VARIABLE_FEE`, `CORRECTION_DISPUTE_FEE`	Positive	Corrects a previously charged fee. Credits the 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 Partner.

Settlement reports