Klarna settlements reconciliation

Reconcile Klarna settlement reports against Payment Transactions, captures, refunds, fees, and payouts. Includes payment cut-off times, payout reference handling, and how to test the settlement flow end-to-end.

Settlement reports give Partners a per-currency breakdown of captured payments, refunds, fees, and disputes — and tie each entry back to the originating Payment Transaction so reconciliation against the Partner's books is straightforward.

Once a Payment Transaction is captured, the applicable rates are applied based on the capture amount. The detailed settlement file includes the calculated fee amount, total amount, net amount, and any tax applied to fees.

Relating a payment to a settlement file

Payouts are made to the bank accounts configured during Klarna onboarding. The payment_reference is included within the metadata in the transfer of funds, following best practices in each market. Use this identifier to correlate a given payout to its associated settlement file.

Each currency results in a separate payout with its own payment_reference.

Relating a transaction to the applied fees

A Payment Transaction can be partially captured or refunded multiple times, and fees are applied per capture. There may therefore be multiple fees associated with any given transaction.

The payment_transaction_id is provided in the settlement file for all actions performed on a Payment Transaction.
The payment_capture_id and payment_capture_reference are associated with a specific capture; payment_refund_id and payment_refund_reference with a specific refund. Use these references to associate a given action with its reconciliation entry.
The dispute_id used to handle disputes is also included in the settlement file, and can be used to understand the fees applied as a result of that action.

Managing adjustments

The settlement file details captures, fees, refunds, disputes, and discounts.

Fees

The settlement file includes the fees applied to each capture event.

Tax (VAT/GST) is applied to the fees if applicable (for example, the EU and Australia).
The fixed and variable rates of the tax are 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_amount values are 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, since the payout is calculated net. If a settlement amount is zero, the outstanding debt is carried over and applied to subsequent settlements.

Debt statement: A debt statement is issued when the Partner has a negative balance (at an aggregate level) for more than 30 days. The statement is not an invoice but a notice that the Partner owes Klarna the negative balance.

Disputes

When a customer disputes a payment, the disputed amount may be withheld from your payouts and a dispute fee may be applied. How a dispute appears in the settlement report depends on your dispute hold policy — see Disputes and chargebacks in the settlement report for the full breakdown. For more on how disputes work, see the Dispute management section.

Other adjustments

Fee correction: A correction applied to 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 (Klarna is reviewing the account) or has INSUFFICIENT_BANK_ACCOUNT_DETAILS (the Partner has not provided complete bank account information required for payouts).

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

Carryover debt balances

If a settlement has a negative balance, that balance is reported as closing_debt_balance in the report and reflected as opening_debt_balance in the subsequent report.

If an account balance remains negative for 30 days, the balance is converted to an invoice and sent to the registered administrative email on the account.

Payment cut-off times

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

The Payout date is when Klarna initiates the payout and publishes the settlement report. The actual arrival of the payout in the Partner's bank account depends on the bank's processing times.

Region	Klarna cut-off time
Europe (including Great Britain)	00:00 London time (UTC in winter, UTC+01:00 in summer)
Asia Pacific	00:00 Sydney time (UTC+10:00 in winter, UTC+11:00 in summer)
North America	00:00 New York time (UTC-05:00 in winter, UTC-04:00 in summer)

Payouts

Payment reference prefix

Partners can request an optional payment reference prefix for payouts.

Length: 4 characters
Usage:
- The prefix is added immediately before the Klarna-generated payment reference.
- The full value (prefix + payment reference) is used in the bank statement.
- The prefix is also included in settlement report file names, directly before the payment reference.

Testing the settlement process

Testing the settlement process ensures that the Partner's 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.

Test the settlement report

To test settlement report generation in the test environment:

1.
Capture Payment Transactions: complete payment captures in the test environment. Optionally, process refunds to include them in the report.
2.
Generate settlement reports: call generateSettlementReports with the Partner's API key. A custom time interval can be specified for captured payments and refunds, or the default interval (last 7 days) can be used. To include additional transactions that Klarna typically generates outside of payment activity (for example, dispute fees, fee corrections, and holdbacks), include them in the request payload as described in the API reference.
3.
Wait for report generation: settlement reports are created asynchronously. When webhooks are configured, Klarna sends a notification when the report is ready. Report generation typically completes within one minute.
4.
Retrieve the settlement report: fetch generated reports using the settlement IDs returned by the API, or list all available reports. All settlement reports are also uploaded to Klarna's SFTP location in the test environment, accessible using the Partner's SFTP credentials. One report is generated per currency and Payment Acquiring Account.

generateSettlementReports API

is only available in the test environment. In production, settlement reports are generated automatically by Klarna according to the Partner's settlement schedule.

Simulate the payout process

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

Once a settlement report has been generated (or if one already exists), set the payout status of the settlement using setSettlementPayoutStatus.
Each time a new payout status is set, Klarna sends a webhook notification (when webhooks are configured for the integration).
The payout status update is asynchronous. After making the request, query getPayout to check the current status.
When the webhook is delivered, the payout status update is complete.

setSettlementPayoutStatus API

is only available in the test environment.

Developer checklist for settlement process testing

Create Payment Transactions in the test environment.
Perform post-purchase actions such as capture, refund, and void.
Generate settlement reports.
Use setSettlementPayoutStatus to simulate payout status changes.
Verify that webhooks are sent for each payout status change (when configured).
Use getPayout to confirm the updated status.
Ensure the integration handles all expected webhook events and payout status transitions.

Disputes and chargebacks in the settlement report

Disputes reasons