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.
7 min read
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,
amountreflects the base amount andtax_is listed separately. Both are deducted from the statement. For example, when a fee line shows anamount amountof-20and atax_ofamount -4, the total deduction from the statement is24. - 7.Validate VAT: use the
tax_field to ensure VAT is calculated correctly.amount
When CSV is the preferred format, steps 2 and 3 can be replaced by a single call to getSettlementCsv.
.For the full reference of all settlement-related operations, see the Klarna Management API reference.
.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.
SFTP authentication limits
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. |
| IP* | 18., 34., 52. | 52., 52., 54. |
| 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_| Element | Description |
|---|---|
file_ | Optional. See Settlement report file name prefix. |
payment_ | Optional. See Payments. |
payment_ | 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). |
File name prefix examples
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.
.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_ | The unique identifier of a settlement. |
settlement_ | Total amount of this settlement. |
currency | The currency of the transaction. |
payment_ | Unique account identifier assigned by Klarna to the Payment Acquiring Account. |
payment_ | Reference for the Payment Acquiring Account. |
When a settlement is finalized, the first webhook is typically
settlement., shortly followed by settlement. and settlement.. 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. |
| Settlement report sent to SFTP | The settlement reports have been uploaded to SFTP. | settlement. |
Settlement payout webhooks
In addition to the common data points shared by all settlement webhooks, the payout webhooks also contain:
| Parameter | Definition |
|---|---|
payout_ | The unique identifier of a payout. |
paid_ | 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_ | A reference to the bank account to which the payout is sent. |
payment_ | 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. | |
| 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. | |
| Settlement payout failed | The payout failed. See status_ for the specific cause. | status (status reasons) | settlement. |
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.
API & SDK references
Jump to section...