Once a transaction is captured, the applicable rates are applied based on the capture amount. The detailed settlement file will include the actual calculated amount of the fees, total amount, net amount, and tax applied to any fees.

Payouts are made to the bank account(s) according to the schedule defined in your settlement configuration. The payment_reference is included within the metadata in the transfer of funds according to best practices in each market. This id may be used to correlate a given payout to the associated settlement file. Each currency will result in a separate payout with its own payment_reference.

A given transaction can be partially captured or refunded multiple times and fees are applied per capture. As such there may be multiple fees associated with any given transaction.

• The payment_transaction_id is provided within the settlement file for all actions regarding a payment transaction.
• The payment_capture_id/payment_capture_reference are only associated with a specific capture, and payment_refund_id/payment_refund_reference with a specific refund. These references may be useful in associating a given action with its reconciliation.
• The dispute_id used to handle disputes is also contained within the settlement file, and can be used to understand the associated fees applied as a result of that action.

The settlement file will detail captures, fees, refunds, disputes, and discounts. Here’s how to manage them:

Fees

The settlement file will include the fees applied to each capture event. These match the effective rates as previously discussed.

• Tax (VAT/GST) will be applied to the fees if applicable (ie. EU and Australia).
• The fixed and variable rates of the tax will be included in the settlement file in the tax_amount field.
• Klarna calculates tax based on the unrounded value of each individual fee on a given capture.
• In the settlement details, tax_amounts will be summarized for ease of consumption.
• The fee amount is separated from the tax (fee_amount + tax_amount = total fee)

Refunds

Refunds are withheld from subsequent payouts, as the payment is NET. If the settlement amount is zero, the outstanding debt will be carried over and applied to subsequent settlements.

• Debt statement: Debt statements are issued if the partner has a negative balance (at an aggregate level) for more than 30 days. This statement is not an invoice but a statement of the partner to pay Klarna of the negative balance.

Disputes

Disputes are also withheld (if won by customer), and a fee may be applied. More details are available in the disputes section.

Other Adjustments

• Fee Correction: A correction applied to correct a previously charged fee in cases where an error occurred related to the application of fees.
• Chargeback: Reverses a transaction following a dispute.
• Holdback/Release: Handles holds or releases. Generally used when an account is UNDER_REVIEW or has INSUFFICIENT_BANK_ACCOUNT_DETAILS.

It is possible that multiple chargebacks may be applied on a single transaction. If this occurs, the transaction details will be included in the settlement as separate lines, ensuring the capture and transaction can be correlated to the chargeback, and the details of the chargeback are also available.

Carryover debt balances

If a settlement has a negative balance, this negative balance will be reported as closing_debt_balance in the report and reflected as an openingdebt_balance in the subsequent report.

Reconciliation requires an understanding of both the buy rates communicated by Klarna and the sell rates applied to Partners.

Rate data: buy rates, set by Klarna, are included within the price plans and can be accessed at any time. Sell rates, however, are determined and managed solely by you as the Acquiring Partner.

Fee data: use the fee data to calculate the fees for each transaction.

• Transactional fees are determined through retrieval of the fees defined in the price plan.
• Any applicable discounts are subtracted.
• If a microtransaction cap applies to the transaction, the lesser of the calculated fee or the cap will be used.
• The variable rate is applied at the time of capture, and the final result will be detailed in the settlement reports.

Acquiring Partners must ensure transparent communication regarding the sell rates offered to Partners to maintain clarity and reduce the risk of Partner-related inquiries. While Acquiring Partners may choose to share buy rates with Partners, only the buy rates directly relevant to the specific Partner may be disclosed.

Cut-off times define which payments will be included in a given day's settlements. All transactions which have been captured or refunded before the cut-off time will be added to the settlement for that period and a payout will be initiated by Klarna on the next banking day. The Settlement Report will normally be available within 24 hours of the cut-off time.

The Payout date is when Klarna initiates the payout to the partner and publishes the Settlement Report. The actual arrival of the payout in the partner’s bank account is dependent on their bank’s processing times.

Options for accessing Klarna settlement reports are summarized below

*refers to Partners ('merchants') for which Klarna is the direct acquirer

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. The file names will be prefixed with a configurable value unique to the Acquiring Partner Account.

Every Settlement Report in the SFTP follows a specific file-naming convention:

AcquiringAccountKey_PaymentReference_currency_timestamp.format

SFTP file contents 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.

Testing the settlement process ensures that your integration with Klarna’s settlement and payout flows works as expected before going live. This section describes how to test both the settlement report and the payout simulation.

To test settlement report generation in the test environment, follow these steps:

1. Capture payment transactions
   1. Complete payment captures in your test environment. Optionally, process refunds to include them in the report.
2. Generate settlement reports
   1. Use the Generate settlement reports API endpoint with your API key. You can specify a custom time interval for captured payments and refunds, or use the default interval (last 7 days).
3. Wait for report generation
   1. Settlement reports are created asynchronously. If you have configured webhooks, Klarna sends a notification when the report is ready. Report generation typically completes within one minute.
4. Retrieve the settlement report
   1. Fetch generated reports using the settlement IDs returned by the API, or list all available reports. All settlement reports are also uploaded to your SFTP server in the test environment.
   2. One report is generated per currency and payment acquiring account.

Limitations

The test settlement reports will only include transactions created by you. Transactions generated by Klarna, such as dispute fees, fee corrections, and holdbacks—are not included in the test environment reports.

You can simulate the payout process for a settlement to verify how your integration handles payout status changes and webhook notifications.

• Once a settlement report is generated (or if one already exists), you can set the payout status of the settlement using the Set payout status endpoint.
  • API reference: Set payout status
• Each time you set a new payout status, Klarna sends a webhook notification (if you have configured webhooks for your integration). Webhook definitions are available in this documentation.
• The payout status update is asynchronous. After making the request, you can query the Get payout status endpoint to check the current status:
  • API reference: Get payout status
• When the webhook is sent, the payout status update is complete.

• Create payment transactions in your test environment.
• Perform post-purchase actions such as capture, refund, and cancel.
• Generate settlement reports.
• Use the Set payout status endpoint to simulate payout status changes.
• Verify that webhooks are sent for each payout status change (if configured).
• Use the Get payout status endpoint to confirm the updated status.
• Ensure your integration handles all expected webhook events and payout status transitions.