Settlement Reports
Ensure accurate payment reconciliation with Klarna’s settlement process, leveraging detailed reports, fee adjustments, and secure API or SFTP access for seamless financial management.
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 contains direct links to the reports.
Workload classification
Retrieving settlement reports in bulk or on a schedule? Send the
Klarna-Workload-Type: background header so these non-time-sensitive calls are metered against a separate rate limit bucket and do not consume your interactive quota. See Workload classification.Steps for reconciliation:
- 1.List settlements: Use the List Settlements request to retrieve a list of settlements over a specific period. You can filter results by time frame, currency, or acquiring entity. The response includes sufficient information to match a payment to its associated settlement report.
- 2.Retrieve settlement report: Use the Get settlement details
to get detailed information about a specific settlement, including the total settlement amount and amounts per transaction type. - 3.Transaction-level reconciliation: Use the List settlement transactions request to retrieve transaction-level details for more granular reconciliation.
- 4.Extract key data: Review key transaction data such as capture amounts, fees, and VAT.
- 5.Get payout details: Use the Get Payout status to obtain details about a specific payout, including the payout amount, currency and status.
- 6.Compare totals: Ensure totals for captures, refunds, fees, and chargebacks match your 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, if a fee line shows aamount amountof -20 and atax_of -4, the total deduction from the statement will be 24.amount - 7.Validate VAT: Use the
tax_field to ensure VAT is calculated correctly. If CSV format is preferred, steps 2 and 3 can be replaced with a call to the Get Settlement Reportamount endpoint.
More information on the requests involved in settlements, and the data contained within the detailed settlement file are available in the API Reference.
.SFTP
Klarna-hosted SFTP is an alternative option for handling Settlement reporting if Klarna's Settlements API and webhooks cannot be used. You may still subscribe to the Settlement Report Created webhook to receive notifications when Settlement reports become available in the SFTP.
Setting up your Klarna SFTP
Using your Klarna API credentials (Account credentials), you may generate SFTP credentials. These credentials include a username and password, which must be stored securely by you.
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.klarna.com | sftp.playground.klarna.net |
| IP* |
|
|
| Protocol | SFTP | SFTP |
| Port | 4001 | 4001 |
*If your security infrastructure requires allowlisting, you must allowlist all listed IPs.
Retrieving Settlement Reports from Klarna SFTP
- Reports will be 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.
If you have multiple Acquiring Partner Accounts (i.e. you maintain multiple acquiring entities), you can access all reports tied to the same Partner Account ID from one directory, regardless of the specific acquiring entity.
SFTP file contents and formatting
Settlement report file name format
Every Settlement Report in the SFTP follows a specific file-naming convention:
<file_| Element | Description |
|---|---|
file_ | Optional. See “Settlement report file name prefix". |
payment_ | Optional. See “Payment reference prefix (payouts) |
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 examples
Examples:
With both prefixes:
ACME_ACME:file name prefixABCD: 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_ABCD: payment reference prefix With no prefixes:123456789_SEK_ 20251015Z. csv
Settlement report filename 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 (-).
- Example 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 will mirror the .csv output of the following API request:
The example provided in the API documentation is the source of truth for structure, formatting, field names, and content of the Settlement Report delivered via SFTP.
Handling failed SFTP settlement file uploads
In the exceedingly rare case that Settlement files fail to upload to the SFTP, Klarna requeues the file for manual intervention. These failures are handled within your contractual SLA with Klarna.
Settlement webhooks
You may choose to receive immediate notifications when certain settlement events occur. The structure of the payload will vary based on the event type, however the metadata will always follow the structure documented in the Configure Klarna Webhook section.
All Settlement webhooks contain these 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 Acquiring Account. |
payment_ | Reference for the Acquiring Account. |
When a settlement is done, the first webhook will probably be the
settlement., shortly followed by settlement. and settlement.. A day or so later, the payout status webhook will be sent.More information on settlement webhooks are available in the API specifications.
Settlement report generation webhooks
| Use case | When | Additional payload | Event name |
| Settlement Report available on API | When the Settlement data has been processed and is available in any format in the API. | links (links to reports) | settlement. |
| Settlement Report sent to SFTP | When the settlement reports have been uploaded to the 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 your bank account. |
payout_ | A reference to the bank account to which the payout is done. |
payment_ | The payment reference used for the payout, will be shown on the bank account statement. |
Settlement payouts generation webhooks
| 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 confirmed by our banking partner. Note that in rare cases an intermediary or the recipient’s bank may still reject it. If that happens, it will be marked failed and we’ll send a failure webhook. | 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.
Jump to section...