Settlement reports

Reconcile Klarna settlements through the Settlements API or Klarna-hosted SFTP. Subscribe to settlement webhooks for real-time notifications, and choose between JSON, CSV, and PDF report formats.

The Settlements API is the recommended approach for managing large volumes of settlement reports. For a complete overview of all available report formats (JSON, CSV, and PDF), delivery channels, and column definitions, see Settlement report types.

Subscribe to the Settlement Report Created webhook to be notified whenever a new report is available. The webhook payload contains direct links to the reports.

Reconciliation through the Settlements API

The recommended reconciliation flow uses the Settlements API end-to-end:

1.
List settlements: call listSettlements to retrieve settlements over a specific period. Filter results by time frame, currency, or acquiring entity. The response includes the data needed to match a payment to its associated settlement report.
2.
Retrieve settlement details: call getSettlement for detailed information about a specific settlement, including the total settlement amount and amounts per transaction type.
3.
Reconcile at transaction level: call getTransactionsBySettlementId to retrieve transaction-level details for granular reconciliation.
4.
Extract key data: review key transaction data such as capture amounts, fees, and VAT.
5.
Get payout details: call getPayout for details about a specific payout, including the payout amount, currency, and status.
6.
Compare totals: ensure totals for captures, refunds, fees, and chargebacks match the Partner's internal data. For each line in the settlement file, amount reflects the base amount and tax_amount is listed separately. Both are deducted from the statement. For example, when a fee line shows an amount of -20 and a tax_amount of -4, the total deduction from the statement is 24.
7.
Validate VAT: use the tax_amount field to ensure VAT is calculated correctly.

When CSV is the preferred format, steps 2 and 3 can be replaced by a single call to getSettlementCsv API

For the full reference of all settlement-related operations, see the Klarna Management API reference API

SFTP

Klarna-hosted SFTP is an alternative option for handling settlement reporting when the Settlements API and webhooks cannot be used. Subscribe to the Settlement Report Created webhook to receive notifications when settlement reports become available on SFTP.

Setting up the Klarna SFTP

Using the Partner's Klarna API credentials, generate SFTP credentials. These credentials include a username and password, which the Partner must store securely.

Klarna's SFTP does not support alternative authentication strategies such as OAuth at this time.

The Klarna SFTP details are:

	Production	Test
Address	`merchants.sftp.klarna.com`	`sftp.playground.klarna.net`
IP^*	`18.200.222.131`, `34.252.46.31`, `52.210.39.241`	`52.213.194.133`, `52.215.64.82`, `54.154.80.99`
Protocol	SFTP	SFTP
Port	4001	4001

^* When the Partner's security infrastructure requires allowlisting, all listed IPs must be allowlisted.

Retrieving settlement reports from Klarna SFTP

Reports become available on the day following the defined cut-off time for each settlement.
Files are stored for 90 days.
Reports are placed at the root level of the SFTP directory.

When the Partner maintains multiple Payment Acquiring Accounts, all reports tied to the same Partner Account ID are accessible from one directory, regardless of the specific acquiring entity.

SFTP file contents and formatting

Settlement report file name format

Every settlement report on SFTP follows a specific naming convention:

<file_name_prefix><payment_reference_prefix><payment_reference>_<currency>_<timestamp>.<format>

Element	Description
`file_name_prefix`	Optional. See Settlement report file name prefix.
`payment_reference_prefix`	Optional. See Payments.
`payment_reference`	Klarna-generated payment reference.
`currency`	ISO 4217 code (for example, `SEK`, `EUR`, `USD`).
`timestamp`	UTC timestamp of report generation (start of day, for example, `20251015Z`).
`format`	Report export format (for example, `csv`).

Examples:

With both prefixes: ACME_ABCD123456789_SEK_20251015Z.csv
- ACME: file name prefix.
- ABCD: payment reference prefix (4 characters for SEK-only accounts).
- 123456789: Klarna-generated payment reference.
With only a file name prefix: ACME_123456789_SEK_20251015Z.csv
With only a payment reference prefix: ABCD123456789_SEK_20251015Z.csv
- ABCD: payment reference prefix.
With no prefixes: 123456789_SEK_20251015Z.csv

Settlement report file name prefix

Partners can request an optional file name prefix for settlement reports.
Validation rules:
- Maximum length: 200 characters.
- Allowed characters: uppercase and lowercase English letters (A–Z, a–z), digits (0–9), underscore (_), and hyphen (-).
- Validation pattern: ^[A-Za-z0-9_-]{1,200}$.
Placement: when configured, the prefix is prepended to the settlement report file name as shown in the file name format above.

Content and formatting

All data contained within the SFTP file mirrors the CSV output of getSettlementCsv API

The example provided in the API documentation is the source of truth for structure, formatting, field names, and content of the settlement report delivered through SFTP.

Handling failed SFTP settlement file uploads

In the rare case that settlement files fail to upload to SFTP, Klarna requeues the file for manual intervention. These failures are handled within the Partner's contractual SLA with Klarna.

Settlement webhooks

Partners can opt in to receive immediate notifications when settlement events occur. The structure of the payload varies by event type, while the metadata always follows the structure documented in the Webhooks registration guide.

All settlement webhooks contain the following data points:

Parameter	Definition
`settlement_id`	The unique identifier of a settlement.
`settlement_amount`	Total amount of this settlement.
`currency`	The currency of the transaction.
`payment_acquiring_account_id`	Unique account identifier assigned by Klarna to the Payment Acquiring Account.
`payment_acquiring_account_reference`	Reference for the Payment Acquiring Account.

When a settlement is finalized, the first webhook is typically settlement.payout.processed, shortly followed by settlement.report.created and settlement.report.uploaded-to-sftp. The payout status webhook follows about a banking day later.

Settlement report generation webhooks

Use case	When	Additional payload	Event name
Settlement report available on the API	The settlement data has been processed and is available in any format on the API.	`links` (links to reports)	`settlement.report.created`
Settlement report sent to SFTP	The settlement reports have been uploaded to SFTP.		`settlement.report.uploaded-to-sftp`

Settlement payout webhooks

In addition to the common data points shared by all settlement webhooks, the payout webhooks also contain:

Parameter	Definition
`payout_id`	The unique identifier of a payout.
`paid_out_at`	The date when Klarna initiated the payout. It usually takes one banking day until the funds are credited to the Partner's bank account.
`payout_bank_account_reference`	A reference to the bank account to which the payout is sent.
`payment_reference`	The payment reference used for the payout, which appears on the bank statement.

Use case	When	Additional payload	Event name
Settlement payout processed	The payout has been processed by Klarna and will shortly be executed.		`settlement.payout.processed`
Settlement payout confirmed	The payout has been confirmed by Klarna's banking partner. In rare cases, an intermediary or the recipient's bank may still reject it; when that happens, the payout is marked as failed and a failure webhook is sent.		`settlement.payout.confirmed`
Settlement payout failed	The payout failed. See `status_reason` for the specific cause.	`status` (status reasons)	`settlement.payout.failed`

Settlement report content

For a detailed breakdown of all report formats (JSON, CSV, PDF), column definitions, CSV formatting conventions, and transaction types, see Settlement report types.

Settlement report types

Klarna settlements reconciliation

Set up your webhooks

API & SDK references

Direct Partner