Klarna v3
Configure Klarna Checkout v3 with Omnium to process payments.
Klarna Checkout v3 Integration with Omnium
Omnium supports Klarna Checkout v3, providing the following features for managing payments:
- Capture payments (full or partial)
- Cancel payments
- Credit/Refund payments
- Release Remaining Authorization when necessary
- Update Merchant ID/Order ID during conversion from cart to order
- Update Authorization to reflect changes in order value without creating a new order
- Extend Authorization Time before expiration
- Update Shipment Information with tracking details after capture
- Retrieve Settlements/Payouts for reconciliation
This integration allows seamless payment management, helping you stay flexible in handling orders and payments.
Setup Instructions
Follow these steps to configure Klarna Checkout in Omnium and get everything working smoothly.
Configuration Path
-
Navigate to:
Configuration > Settings > Payment > Payment Types > "..." > Add -
Fill out the required fields as outlined below.
Required Fields
| Field | Description | Value |
|---|---|---|
| Unique Payment Name | The unique identifier for the Klarna Checkout payment method. | KlarnaCheckout |
| Payment Service | The name of the payment service used for this configuration. | KlarnaCheckout |
| Provider Name | Specifies which provider to use for processing the payment. | Klarna |
| Display Name | The name shown to customers in the checkout process. | Klarna Checkout v3 |
| Base URL | The target URL for the Klarna API (see Base URL Options below). | https://api.playground.klarna.com (test) or https://api.klarna.com (production) |
| Vue Template | The template for payment method integration. | klarna-v3-payment |
| Merchant ID | Your unique identifier for Klarna, provided by the provider. | Your Merchant ID from Klarna |
| API Token | The API token used for authentication, provided by Klarna. | Your API Token from Klarna |
Base URL Options
Klarna supports multiple regional environments. Use the appropriate Base URL for your market and environment:
| Region | Environment | Base URL |
|---|---|---|
| Europe | Production | https://api.klarna.com |
| Europe | Sandbox/Test | https://api.playground.klarna.com |
| North America | Production | https://api-na.klarna.com |
| North America | Sandbox/Test | https://api-na.playground.klarna.com |
You can also use the following shortcuts as the Base URL value:
| Shortcut | Resolves To |
|---|---|
eubaseurl | https://api.klarna.com |
eutestbaseurl | https://api.playground.klarna.com |
nabaseurl | https://api-na.klarna.com |
natestbaseurl | https://api-na.playground.klarna.com |
Additional Configuration
Display Options
| Setting | Description | Default |
|---|---|---|
| Display in Cart | Set to true to show the Klarna payment option in the shopping cart interface. | false |
| Editable | Allow editing payment details in the GUI. | false |
| Hidden | Hide this payment method from the GUI entirely. | false |
| Read Only | Make this payment method read-only in the GUI. | false |
| Logo URL | URL to a custom logo image to display in the GUI. | - |
Authorization Settings
| Setting | Description | Default |
|---|---|---|
| Enable Update Authorization Amount | Allow updating the authorized amount from the GUI (e.g., when order value changes). | false |
| Enable Extend Authorization Time | Allow extending the authorization expiration time from the GUI. | false |
| Authorization Time In Days | Default authorization expiration time in days (informational, actual expiration set by Klarna). | 0 |
Market & Store Restrictions
| Setting | Description | Default |
|---|---|---|
| Valid On Markets | Restrict this payment method to specific markets. Leave empty for all markets. | All markets |
| Valid For Stores | Restrict this payment method to specific stores. Leave empty for all stores. | All stores |
Operational Settings
| Setting | Description | Default |
|---|---|---|
| Disable Transactions | Prevent new transactions from being created with this payment method. | false |
| Get Details From Provider | Enable fetching real-time payment details from Klarna via "Get payment information" action. | false |
Priority Settings
| Setting | Description | Default |
|---|---|---|
| Credit Priority | Priority for refund processing when order has multiple payments. Lower value = higher priority. | 0 |
| Capture Priority | Priority for capture when order has multiple payments. Lower value = higher priority. | 0 |
Reporting
| Setting | Description | Default |
|---|---|---|
| Payment Provider Fee | Fee percentage charged by the payment provider. Used in reports. | 0 |
Advanced Features
Update Authorization Amount
When enabled via Enable Update Authorization Amount, you can update the authorized amount on an order without creating a new Klarna order. This is useful when:
- Order value changes after authorization (e.g., item quantity adjustment)
- Customer adds or removes items before capture
The update is performed through the order's payment actions in the GUI.
Extend Authorization Time
Klarna authorizations have an expiration time. When enabled via Enable Extend Authorization Time, you can extend the authorization before it expires. This is useful for orders with longer fulfillment times.
Shipment Information Updates
After capturing a payment, you can update the shipment information with:
- Shipping Company/Carrier: The name of the shipping carrier
- Tracking Number: The shipment tracking identifier
- Tracking URI: A link to track the shipment
- Shipping Method: The type of shipping (e.g., postal delivery, pickup point, store pickup)
This information is sent to Klarna and can be displayed to the customer.
Settlements/Payouts
Omnium can retrieve settlement and payout data from Klarna for reconciliation purposes. Settlement data includes:
- Sales transactions: Captured payments
- Refund transactions: Credited/refunded payments
- Fee transactions: Klarna processing fees
Settlement data can be filtered by date range and currency.
Get Payment Details
When Get Details From Provider is enabled, you can fetch real-time payment information from Klarna, including:
- Current order status
- Captured amount vs. remaining authorized amount
- Refunded amount
- Order lines
- Capture history with tracking information
- Authorization expiration date
Klarna In-Store
In addition to standard Klarna Checkout v3, Omnium also supports Klarna In-Store for physical retail locations. This uses a hosted payment page (HPP) that can be sent to customers via SMS or email.
Setup for Klarna In-Store
Use the following values when configuring Klarna In-Store:
| Field | Value |
|---|---|
| Unique Payment Name | KlarnaInStore |
| Payment Service | KlarnaInStore |
| Provider Name | Klarna |
| Vue Template | klarna-instore-payment |
Klarna In-Store Flow
- A Klarna checkout order is created
- A hosted payment page (HPP) session is generated
- A payment link is distributed to the customer via SMS or email
- The customer completes payment on the hosted page
- The system polls for session completion
- On completion, an authorization transaction is created
- Standard capture/refund flow proceeds from there
Refund Limitations
Standard Refunds
Standard refunds are supported for all Klarna markets. You can perform:
- Full refunds: Refund the entire captured amount
- Partial refunds: Refund a portion of the captured amount with specific order lines
Return Fee (Refund Charge)
Klarna supports charging a return fee when processing refunds in certain markets. However, this feature has the following conditions:
- The order must be fully captured in a single capture (no partial captures)
- The sum of the refunded order lines must exactly match the refund amount
- Supported markets: Austria, Germany, Denmark, Finland, France, Netherlands, Norway, Sweden
The return fee feature requires specific configuration. Contact support if you need this functionality enabled.
Order Line Handling
When sending order data to Klarna, the following rules apply:
| Aspect | Behavior |
|---|---|
| Tax Handling | Taxes are always included in unit prices and total amounts |
| Reference Length | Order line references are truncated to 64 characters (Klarna limit) |
| Quantity Rounding | Quantities less than 1 are rounded up to 1 (Klarna doesn't accept decimals < 1) |
| Line Types | Supported: physical, shipping_fee, store_credit, discount, return_fee |
Troubleshooting
Common Issues
| Issue | Possible Cause | Solution |
|---|---|---|
| Authentication failed | Invalid Merchant ID or API Token | Verify credentials in Klarna Merchant Portal |
| Order not found | Transaction ID doesn't match Klarna order | Check that the correct environment (test/prod) is used |
| Capture failed | Authorization expired or already captured | Check authorization status and expiration date |
| Refund failed | Amount exceeds captured amount or order not captured | Verify capture status before refunding |
| Update authorization failed | Order already captured or cancelled | Authorization updates only work on authorized orders |
Error Handling
Klarna errors are logged and displayed on the order in the Errors section. Check the order details for detailed error messages from Klarna when a payment operation fails.
Supported Operations
| Operation | Klarna Checkout v3 | Klarna In-Store |
|---|---|---|
| Capture | Yes | Yes |
| Partial Capture | Yes | Yes |
| Cancel | Yes | Yes |
| Refund | Yes | Yes |
| Partial Refund | Yes | Yes |
| Update Authorization | Yes | Yes |
| Extend Authorization | Yes | Yes |
| Release Remaining Auth | Yes | Yes |
| Update Shipment Info | Yes | Yes |
| Get Details | Yes | Yes |
| Get Settlements | Yes | Yes |
| In-Store HPP | No | Yes |