Request settlement currency
Request the currency Klarna uses to settle a Payment Transaction. Useful when the transaction currency differs from the currency Klarna should pay out in.
5 min read
Partners can request the currency Klarna uses when settling a Payment Transaction. This allows transacting in any supported currency and still receiving payouts in one of the enabled settlement currencies. See Supported settlement currencies for the full list.
The settlement currency is requested explicitly during Payment Authorization, in the 
request.
acquiring_config block of the authorizePayment request.When no settlement currency is requested:
- Klarna attempts to settle in the Payment Transaction
currency. - If the Payment Transaction currency is not enabled for the Partner and default selection is enabled for the account, Klarna selects a supported default settlement currency and returns it on the Payment Transaction. Otherwise, the request returns
400.
Settlement currency example
Example: A US-based Partner sells to an EU customer and authorizes the Payment Transaction in EUR. The Partner sets
settlement_currency = USD so Klarna settles the transaction in USD.flowchart TD
A[Settlement currency requested?] -->|Yes| B[Validate against your enabled settlement currencies]
B -->|Valid| C[Use requested settlement currency]
B -->|Not valid| D[Return 400: Settlement currency not supported]
A -->|No| E[Use Payment Transaction currency]
E -->|Enabled| F[Use Payment Transaction currency as settlement currency]
E -->|Not enabled| G[Klarna selects a default settlement currency]
Specify the desired settlement currency in the :
acquiring_config block when calling authorizePayment:JSON
1
2
3
4
5
6
7
8
9
{
"currency": "SEK",
"request_payment_transaction": {
"amount": 2000
},
"acquiring_config": {
"settlement_currency": "USD"
}
}settlement_currency must be a value from the Partner's enabled settlement currencies (ISO 4217 format). It can be combined with the routing fields (payment_account_id or payment_acquiring_account_id + payment_account_reference) when the Partner's Klarna setup includes more than one Payment Account.Default settlement currency behavior
If
settlement_currency is not provided, Klarna attempts to settle using the currency of the Payment Transaction. If that currency is not enabled for the Partner and default selection is enabled for the account, Klarna selects a supported default settlement currency. Otherwise, the request returns 400.JSON
1
2
3
4
5
6
7
8
9
10
{
"payment_transaction_response": {
"result": "APPROVED",
"payment_transaction": {
"payment_transaction_id": "krn:payment:eu1:transaction:6debe89e-98c0-486e-b7a5-08a4f6df94b0",
"payment_transaction_reference": "partner-transaction-reference-1234",
"amount": 2000,
"currency": "SEK",
"state": "COMPLETED",
"settlement_currency": "USD",The chosen settlement currency is returned on the Payment Transaction in
settlement_currency and is fixed for the lifetime of the transaction.Unsupported settlement currency returns 400
If the requested settlement currency is not enabled for the Partner, Klarna returns
400 with the message Settlement currency not supported.After authorization, capture the Payment Transaction with capturePaymentTransaction as usual. The requested settlement currency applies to all downstream events (captures, refunds, fees, chargebacks).
as usual. The requested settlement currency applies to all downstream events (captures, refunds, fees, chargebacks).Currency conversion happens at the moment each Payment Transaction event occurs (capture, refund, etc.), using the spot rate available at the event time.
The Settlement Report consists of one or more Partner Balance Transactions — individual entries for each capture, refund, fee, dispute, or adjustment. When the Payment Transaction is settled, the converted amount appears as a Partner Balance Transaction entry in the report. The following fields enable reconciling the settled amount back to the original Payment Transaction event:
| Field | Populated when | Description |
|---|---|---|
amount | Always | The amount settled for this Partner Balance Transaction, in minor units. Negative for debits, positive for credits. |
currency | Always | The settlement currency (ISO 4217). |
transaction_event_amount | Only when conversion occurred | The original amount of the Payment Transaction event before conversion, in minor units. |
transaction_event_currency | Only when conversion occurred | The original currency of the Payment Transaction event before conversion. |
exchange_rate | Only when conversion occurred | The rate applied: transaction_event_amount × exchange_rate = amount. |
- Fixed fees are defined in the Partner's price plan.
- Variable fees are calculated from the original amount of each event, then converted.
- All fees follow the same settlement currency as the related capture.
- Converted fees include the same reconciliation fields as Payment Transaction events.
- 1.Create a Payment Transaction with a specified
settlement_currency. - 2.Create another without specifying it and observe the default Klarna selects.
- 3.Capture the Payment Transaction.
- 4.Generate a Settlement Report with generateSettlementReports in the test environment.
- 5.Verify the converted amounts and reconciliation fields.
Cause: The requested currency is not enabled for the Partner.
Action: Choose a currency from Supported settlement currencies, or contact Klarna Support to enable it.
Cause: The Payment Transaction was authorized in a currency Klarna cannot settle for the Partner, and the account is not enabled for default selection.
Action: Contact Klarna Support to verify enablement.
Jump to section...