Settlement Reports

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.

1. 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. 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. 3.
   Transaction-level reconciliation: Use the List settlement transactions request to retrieve transaction-level details for more granular reconciliation.
4. 4.
   Extract key data: Review key transaction data such as capture amounts, fees, and VAT.
5. 5.
   Get payout details: Use the Get Payout status to obtain details about a specific payout, including the payout amount, currency and status.
6. 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. 7.
   Validate VAT: Use the tax_amount 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 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 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.

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.

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

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

<file_name_prefix><payment_reference_prefix><payment_reference><currency>_<timestamp>.<format>

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

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.

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.

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:

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.

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

For a detailed breakdown of all report formats (JSON, CSV, PDF), column definitions, CSV formatting conventions, and transaction types, see Settlement report types.