openapi: 3.0.0 paths: /payouts/summary: get: parameters: - in: query name: start_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z. required: true schema: type: string format: date-time - in: query name: end_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full datetime like 2020-01-23T23:59:59Z. required: true schema: type: string format: date-time - in: query name: currency_code description: >- An optional currency code to filter the result for different currencies. If not provided the result returned in the response might include multiple results grouped by the currency. The currency should be provided by an ISO 4217 Currency Code like USD, EUR, AUD or GBP. required: false schema: type: string responses: '200': description: Payout summaries content: application/json: schema: type: array items: $ref: '#/components/schemas/PayoutSummary' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' operationId: getPayoutSummary summary: Klarna Payout summary description: Returns a summary of payouts for each currency code in a date range. tags: - Payouts /payouts/{payment_reference}: get: parameters: - in: path name: payment_reference description: >- The reference id of the payout. Normally this reference can be found on your payment slip statement of your bank. required: true schema: type: string responses: '200': description: A payout content: application/json: schema: $ref: '#/components/schemas/Payout' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' operationId: getPayout summary: Klarna Payout details description: Returns a specific payout based on a given payment reference. tags: - Payouts /payouts: get: parameters: - in: query name: start_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z. required: false schema: type: string format: date-time - in: query name: end_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full date time like 2020-01-23T23:59:59Z. required: false schema: type: string format: date-time - in: query name: currency_code description: >- An optional currency code to filter the result for different currencies. If not provided the result returned in the response might include multiple results grouped by the currency. The currency should be provided by an ISO 4217 Currency Code like USD, EUR, AUD or GBP. required: false schema: type: string - in: query name: size description: >- How many elements to include in the result. If no value for size is provided, a default of 20 will be used. A maximum of 500 can be set required: false schema: type: integer format: int64 maximum: 500 default: 20 - in: query name: offset description: >- The current offset. Describes "where" in a collection the current starts. required: false schema: type: integer format: int64 default: 0 responses: '200': description: A collection of payouts content: application/json: schema: $ref: '#/components/schemas/PayoutCollection' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' operationId: getPayouts summary: Klarna List all payouts description: Returns a collection of payouts. tags: - Payouts /reports/payout-with-transactions: get: parameters: - in: query name: payment_reference description: The reference id of the payout required: true schema: type: string responses: '200': description: A payout '400': description: Bad request content: text/csv: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: text/csv: schema: $ref: '#/components/schemas/ErrorResponse' operationId: getPayoutReportWithTransactions summary: Klarna Get a payouts summary (CSV) description: |- More information about this CSV format is available at: https://docs.klarna.com/settlement-reports tags: - Reports /reports/payout: get: parameters: - in: query name: payment_reference description: The reference id of the payout required: true schema: type: string responses: '200': description: A payout '400': description: Bad request content: application/pdf: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/pdf: schema: $ref: '#/components/schemas/ErrorResponse' operationId: payout summary: Klarna Get a payouts summary (PDF) description: A single settlement summed up in pdf format tags: - Reports /transactions: get: parameters: - in: query name: payment_reference description: The reference id of the payout required: false schema: type: string - in: query name: order_id description: The Klarna assigned order id reference required: false schema: type: string - in: query name: size description: >- How many elements to include in the result. If no value for size is provided, a default of 20 will be used. A maximum of 500 can be set. required: false schema: type: integer format: int64 maximum: 500 default: 20 - in: query name: offset description: >- The current offset. Describes "where" in a collection the current starts. required: false schema: type: integer format: int64 default: 0 responses: '200': description: A collection of payouts content: application/json: schema: $ref: '#/components/schemas/TransactionCollection' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' operationId: getTransactions summary: Klarna List transactions in a payout description: Returns a collection of transactions. tags: - Transactions /reports/payouts-summary-with-transactions: get: parameters: - in: query name: start_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z. required: true schema: type: string format: date-time - in: query name: end_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full date time like 2020-01-23T23:59:59Z. required: true schema: type: string format: date-time responses: '200': description: A summary of payouts '400': description: Bad request content: text/csv: schema: $ref: '#/components/schemas/ErrorResponse' operationId: getPayoutsSummaryReportWithTransactions summary: Klarna Get a payouts summary with transactions (CSV) description: |- More information about this CSV format is available at: https://docs.klarna.com/settlement-reports tags: - Reports /reports/payouts-summary: get: parameters: - in: query name: start_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. For example 2020-01-23 -> 2020-01-23T00:00:00Z. For this reason we recommend too use the full datetime like 2020-01-23T00:00:00Z. required: true schema: type: string format: date-time - in: query name: end_date description: >- ISO 8601 date time format. This is a filter for the payout date. If no time is given then it defaults to the start of the day, ie 00:00:00. This might lead to unwanted side effects like when the start date and end date might be the same because it would request payouts between 2020-01-23T00:00:00Z and 2020-01-23T00:00:00Z. Instead we advise to use a full date time like 2020-01-23T23:59:59Z. required: true schema: type: string format: date-time responses: '200': description: A summary of payouts '400': description: Bad request content: application/pdf: schema: $ref: '#/components/schemas/ErrorResponse' operationId: payoutsSummary summary: Klarna Get a payouts summary with transactions (PDF) description: Returns a summary for all payouts between the given dates tags: - Reports info: title: Klarna Settlements API description: >- The Settlements API helps you with the reconciliation of payments, made by Klarna to your bank account. Every payment has a unique payment_reference that can be found in the settlement reports and on your bank statement. Read more on [Settlement reports](https://docs.klarna.com/settlement-reports/). # Authentication version: 1.0.0-rc2 servers: - url: https://api.klarna.com/settlements/v1 components: securitySchemes: basic_auth: type: http scheme: basic schemas: ErrorResponse: type: object properties: error_code: description: ERROR_CODE type: string error_messages: description: Array of error messages type: array items: type: string correlation_id: description: Unique id for this request used for troubleshooting. example: 2fe0311b-adc5-45e5-ac2b-963dac83c88b type: string additionalProperties: false required: - error_code - error_messages - correlation_id Pagination: type: object properties: count: description: The amount of elements in the current result example: 10 type: integer format: int64 total: description: The total amount of elements that are available example: 42 type: integer format: int64 next: description: The URI to the next "page" of results. example: http://example.com/collection?offset=21&size=10 type: string prev: description: The URI to the previous "page" of results. example: http://example.com/collection?offset=0&size=10 type: string offset: description: >- The current offset. Describes "where" in a collection the current starts. example: 10 type: integer format: int64 additionalProperties: false required: - count Payout: type: object properties: totals: $ref: '#/components/schemas/Totals' payment_reference: description: The reference id of the payout example: XISA93DJ type: string payout_date: description: ISO 8601 formatted date-time string example: '2016-12-14T07:52:26Z' type: string format: date-time currency_code: description: ISO 4217 Currency Code. Like USD, EUR, AUD or GBP. example: USD type: string currency_code_of_registration_country: type: string description: ISO 4217 Currency Code of the country you are registered in. example: EUR merchant_settlement_type: description: Whether the amounts are net or gross example: NET type: string enum: - GROSS - NET - GROSS_FEE merchant_id: description: The merchant id type: string transactions: description: Link to the transactions that are part of this payout example: https://{settlements_api}/transactions?payment_reference=XISA93DJ type: string additionalProperties: false required: - totals - payment_reference - payout_date - currency_code - merchant_settlement_type - merchant_id PayoutCollection: type: object properties: payouts: type: array items: $ref: '#/components/schemas/Payout' pagination: $ref: '#/components/schemas/Pagination' additionalProperties: false required: - payouts - pagination PayoutSummary: type: object properties: summary_total_fee_correction_amount: description: The total amount of fee correction, in minor units example: 550 type: integer format: int64 summary_payout_date_start: description: ISO 8601 formatted date-time string example: '2016-12-14T07:52:26Z' type: string format: date-time summary_total_release_amount: description: >- The total amount of money released from holdback by Klarna, in minor units example: 550 type: integer format: int64 summary_settlement_currency: description: ISO 4217 Currency Code. Like USD, EUR, AUD or GBP. example: USD type: string summary_payout_date_end: description: ISO 8601 formatted date-time string example: '2016-12-14T07:52:26Z' type: string format: date-time summary_total_tax_amount: description: The total amount of tax, in minor units example: 550 type: integer format: int64 summary_total_settlement_amount: description: The total amount of the settlement in question, in minor units example: 550 type: integer format: int64 summary_total_holdback_amount: description: The total amount of money withheld by Klarna, in minor units example: 550 type: integer format: int64 summary_total_reversal_amount: description: The total amount of reversals, in minor units example: 550 type: integer format: int64 summary_total_return_amount: description: The total amount of returns, in minor units example: 550 type: integer format: int64 summary_total_fee_amount: description: The total amount of fees, in minor units example: 500 type: integer format: int64 summary_total_commission_amount: description: The total amount of commissions, in minor units example: 550 type: integer format: int64 summary_total_sale_amount: description: The total amount of sales, in minor units example: 500 type: integer format: int64 summary_total_repay_amount: description: >- The total amount of money that has been repaid by the merchant from the debt to Klarna, in minor units example: 550 type: integer format: int64 additionalProperties: false required: - summary_total_fee_correction_amount - summary_payout_date_start - summary_total_release_amount - summary_settlement_currency - summary_payout_date_end - summary_total_tax_amount - summary_total_settlement_amount - summary_total_holdback_amount - summary_total_reversal_amount - summary_total_return_amount - summary_total_fee_amount - summary_total_commission_amount - summary_total_sale_amount - summary_total_repay_amount Totals: type: object properties: commission_amount: description: The total amount of commissions, in minor units example: 550 type: integer format: int64 repay_amount: description: >- The total amount of money that has been repaid by the merchant from the debt to Klarna, in minor units example: 550 type: integer format: int64 sale_amount: description: The total amount of sales, in minor units example: 500 type: integer format: int64 holdback_amount: description: The total amount of money withheld by Klarna, in minor units example: 550 type: integer format: int64 tax_amount: description: The total amount of tax, in minor units example: 550 type: integer format: int64 settlement_amount: description: The total amount of the settlement in question, in minor units example: 550 type: integer format: int64 fee_correction_amount: description: The total amount of fee correction, in minor units example: 550 type: integer format: int64 reversal_amount: description: The total amount of reversals, in minor units example: 550 type: integer format: int64 release_amount: description: >- The total amount of money released from holdback by Klarna, in minor units example: 550 type: integer format: int64 return_amount: description: The total amount of returns, in minor units example: 550 type: integer format: int64 fee_amount: description: The total amount of fees, in minor units example: 500 type: integer format: int64 charge_amount: description: >- The total amount of charges, in minor units. The additional field detailed_type contains the purpose of the charge example: 500 type: integer format: int64 credit_amount: description: >- The total amount of credits, in minor units. The additional field detailed_type contains the purpose of the credit example: 500 type: integer format: int64 fee_refund_amount: description: >- The total amount of refunded fees in a given settlement, in minor units. example: 500 type: integer format: int64 tax_refund_amount: description: >- The total amount of refunded tax in a given settlement, in minor units. example: 500 type: integer format: int64 deposit_amount: description: >- The increase of your debt balance with Klarna if your returns, fees, and other charges exceed your sales within this settlement period. This debt will be deducted from your next settlements and describes the amount that is increasing your debt balance, to be seen in the closing_debt_balance. In minor units. example: 500 type: integer format: int64 opening_debt_balance_amount: description: >- Your negative balance with Klarna from previous settlements, if your returns, fees, and other charges exceeded your sales. This amount equals the closing_debt_balance of your last settlement unless Klarna has invoiced you separately for the amount. In minor units. example: 500 type: integer format: int64 closing_debt_balance_amount: description: >- Your debt balance after the settlement. This amount will be the opening debt balance of your next settlement and helps you understand which amounts will be deducted from your next settlements. In minor units. example: 500 type: integer format: int64 additionalProperties: false required: - commission_amount - repay_amount - sale_amount - holdback_amount - settlement_amount - reversal_amount - release_amount - return_amount - fee_amount - charge_amount - credit_amount - fee_refund_amount - tax_refund_amount - deposit_amount - opening_debt_balance_amount - closing_debt_balance_amount Transaction: type: object properties: amount: description: Total amount of the specific transaction, in minor units example: 2000 type: integer format: int64 capture_id: description: >- Each capture on an order is assigned a unique identifier, referred to as the capture_id, which is provided exclusively for sale and fee transactions. In instances of partial shipments, an order may undergo multiple captures, each of which is reflected as a separate transaction with its own unique capture_id. It's important to note that for certain transaction types such as RETURNS and REVERSALS, where captures do not exist, the API will return empty strings for the capture_ID field. example: 33db6f16-9f43-43fa-a587-cc51411c98e4 type: string merchant_reference1: description: >- Merchant assigned reference, typically a reference to an order management system id type: string sale_date: description: ISO 8601 formatted date-time string example: '2016-12-14T07:52:26Z' type: string format: date-time type: description: The type of transaction. example: SALE type: string enum: - COMMISSION - SALE - REVERSAL - RETURN - TAX - FEE - FEE_REFUND - CORRECTION - REVERSAL_MERCHANT_PROTECTION - CHARGE - CREDIT - HOLDBACK - RELEASE capture_date: description: ISO 8601 formatted date-time string example: '2016-12-14T07:52:26Z' type: string format: date-time payment_reference: description: >- Reference to the specific payout the transaction is part of, if available. example: XISA93DJ type: string order_id: description: The Klarna assigned order id reference example: ce17b4cb-147f-48b7-b8e6-dde2fa397f04 type: string format: uuid payout: description: Link to the payout that this transaction is part of example: https://{settlements_api}/payouts/XISA93DJ type: string refund_id: description: The Klarna assigned id reference of a specific refund example: ef1baa1f-b42e-44be-b9e4-4b94510b53e5 type: string short_order_id: description: The Klarna assigned short order id reference example: shortrid type: string merchant_reference2: description: >- Merchant assigned reference, typically a reference to an order management system id type: string currency_code: description: ISO 4217 Currency Code. Like USD, EUR, AUD or GBP. example: USD type: string purchase_country: type: string description: ISO Alpha-2 Country Code example: PL vat_rate: type: integer description: VAT (Value added tax) rate on Klarna fees example: 2000 vat_amount: type: integer description: VAT (Value added tax) amount on Klarna fees, in minor units example: 1000 shipping_country: type: string description: ISO Alpha-2 Country Code example: PL initial_payment_method_type: type: string description: Payment method the consumer chose during checkout example: direct_debit initial_number_of_installments: type: integer description: >- Number of installments the consumer chose during checkout in case of installment payments example: 3 initial_payment_method_monthly_downpayments: type: integer description: >- Number of monthly downpayments that were chosen during the checkout in case of installment payments. example: 12 merchant_capture_reference: type: string description: >- Your internal reference to the capture, that has been submitted during capturing an order via API merchant_refund_reference: type: string description: >- Your internal reference to the refund, that has been submitted during refunding an order via API detailed_type: type: string description: Detailed description of the transaction type example: PURCHASE enum: - COMMISSION - CREDITED_CORRECTION - PURCHASE_FEE_PERCENTAGE - PURCHASE_FEE_PERCENTAGE_REFUND - LATE_RETURN_FEE - PURCHASE_FEE_FIXED - EXPIRY_FEE_GROSS - EXPIRY_FEE - SERVICING_FEE - RETURN_FEE - EXTRA_INVOICE_FEE - PURCHASE_RETURN - COMMISSION_RETURN - REVERSAL - FRAUD_POLICY_CHARGE - COMMISSION_RETURN_GROSS - FRAUD_POLICY_CREDIT_NET - PURCHASE - MANUAL_ENTRY - LOAN_PAYOUT - LOAN_AMORTISATION - LOAN_FEE - FEE_REFUND - PURCHASE_COMMISSION_PERCENTAGE - EXTEND_DUE_DATE_FEE - TRANSFER_FROM_LEGACY_INTEGRATION - FIXED_FEE_CORRECTION_UK - PERCENTAGE_FEE_CORRECTION_UK - VAT_ON_FEE_CORRECTION_UK - FIXED_FEE_CORRECTION_SE - PERCENTAGE_FEE_CORRECTION_SE - PERCENTAGE_FEE_CORRECTION - FIXED_FEE_CORRECTION - ROLLING_RESERVE - PERCENTAGE_FEES - PAYMENT_REMINDER - CORRECTION - UNDER_REVIEW - INSUFFICIENT_BANK_ACCOUNT_DETAILS - DISPUTE_FEE - DISPUTE_FEE_REFUND - CORRECTION_DISPUTE - PAYMENT_DEFAULT tax_in_currency_of_registration_country: type: integer description: >- The tax amount on the respective fee, converted into the currency of your registration country. In case you are a German merchant selling in another currency then EUR or a Swedish merchant selling in another currency then SEK, we convert the VAT amount on the Klarna fees into the currency of the country you are registered in, based on the exchange rate of the capture date. example: 1000 currency_code_of_registration_country: type: string description: ISO 4217 Currency Code of the country you are registered in. example: EUR klarna_comment: type: string description: >- Any additional information necessary to provide more context about the transaction. example: Loan Amortisation 2022-12-01 reversal_reference: type: string description: >- Unique internal identifier, known as DisputeKRN, assigned to each dispute by Klarna. This identifier includes a dispute category and a numeric code, enabling efficient tracking and management of the dispute's status. example: krn:klarna:eu1:dispute:goods_not_received:263099944398666 additionalProperties: false required: - amount - sale_date - type - capture_date - order_id - currency_code - purchase_country TransactionCollection: type: object properties: transactions: type: array items: $ref: '#/components/schemas/Transaction' pagination: $ref: '#/components/schemas/Pagination' additionalProperties: false required: - transactions - pagination tags: - name: Payouts - name: Reports - name: Transactions