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.
53 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.
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.
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
| 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 | getSettlementTaxInvoice | API, SFTP | Tax documentation with Settlement breakdown |
The JSON endpoints give you programmatic access to Settlement data with structured objects and cursor-based pagination.
Use getSettlement to retrieve the totals for a specific Settlement. The response includes the Settlement amount, currency, period, and a
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.Use getTransactionsBySettlementId to retrieve individual transactions for a Settlement. The response uses cursor-based pagination — pass
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.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.
The getSettlementCsv endpoint returns a single CSV file containing both the Settlement summary and individual transactions.
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.
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_referenceInfo
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_referenceThe getSettlementSummaryReport endpoint returns a standard CSV with one header row and one data row containing Settlement totals and payout details.
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.
The getSettlementTransactionsReport 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
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.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.
The getSettlementTaxInvoice 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:
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.
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 |
Jump to section...