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.
47 min read
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.
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.
SFTP setup details
For SFTP setup, file name conventions, and server connection details, see Settlement reports.
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
| 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 | getSettlementTaxInvoice | API, SFTP | Tax documentation with settlement breakdown. |
The JSON endpoints provide 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 is not 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. When the Partner's 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_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.The 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.00is represented as100. - Amount signs: positive values are credits, negative values are debits.
- Percentages: integer in minor units.
15.57%is represented as1557.
Integration requirement
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.
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). The Partner's 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 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. |
Related articles
Jump to section...