The Settlements API is the recommended approach for managing large volumes of settlement reports.

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

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, amount reflects the base amount and tax_amount is listed separately. Both are deducted from the statement. For example, if a fee line shows a amount of -20 and a tax_amount of -4, the total deduction from the statement will be 24.
7. Validate VAT: Use the tax_amount field to ensure VAT is calculated correctly.

If CSV format is preferred, step 2 and 3 can be replaced with a call to the Get Settlement Report endpoint.

More information on the requests involved in settlements, and the data contained within the detailed settlement file are available in the API Reference.

Klarna-hosted SFTP is a 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 availalbe 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.

The Klarna SFTP details are:

*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 Klarna Network 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_name_prefix><payment_reference_prefix><payment_reference><currency>_<timestamp>.<format>

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:

GET /settlements/{settlement_id}/csv

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 a 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.

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 contains these data points:

When a settlement is done, the first webhook will probably be the settlement.payout.processed, shortly followed by settlement.report.created and settlement.report.uploaded-to-sftp. 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

Settlement payout webhooks

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

Settlement payouts generation webhooks

Both JSON and CSV report formats contain the same data and field names.

The CSV format (whether retrieved from Klarna SFTP or via API) contains both the settlement summary and the itemized transactions, within a single report.

The JSON format makes the summary and the itemized transactions available as separate API requests:

• Get Settlement summary
• List Settlement transactions

For documentation of the field names, description and examples, please look at the API specifications for Get settlement details and List settlement transactions

Transaction types

The transaction types are documented in the API in the Transactions definition. Depending on the transaction type and use case, not all fields in the transaction are populated. Use the API and filter using transaction type.