VibeFox Klarna for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. Without WooCommerce the plugin refuses to activate.

PHP: 8.0 or later.

HTTPS: Klarna requires HTTPS for live payments.

Klarna merchant account: you need the Klarna API credentials (username and password) of your merchant account for one API region, and test credentials from the Klarna playground portal (see Configuration). Each API region has its own credentials. Only one merchant account (one API region) can be used per shop.

Store currency: a Klarna currency of your region: EUR, SEK, NOK, DKK, GBP, CHF, PLN, CZK, HUF or RON in Europe; USD, CAD or MXN in North America; AUD or NZD in Oceania.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_klarna_payment folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Klarna Payments > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Choose the API region of your Klarna merchant account.

6. Enter the test username and password from the Klarna playground portal, keep Test mode on, turn on Enable/Disable and place a test order.

7. Enter the live username and password from the Klarna Merchant Portal, untick Test mode and choose when orders are captured (default: when the order is marked Completed).

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Klarna Payments. Next to the page title a badge shows TEST MODE or LIVE. The page warns you when the username or password of the active mode is missing (Klarna is then hidden at checkout) and when the store currency is not sold by Klarna in the selected API region. In the list of payment methods, Klarna is marked as needing setup until the credentials of the active mode are entered, and shows a test mode badge while test mode is on.

General

Enable/Disable: Enable Klarna Payments turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Klarna.

Description: the text shown to the customer above the Klarna widget. Default: Pay now, later or in instalments with Klarna.

API credentials

Klarna API credentials (username and password) are created in the Klarna Merchant Portal (portal.klarna.com) under Settings > Klarna API credentials. Test credentials come from the playground portal: playground.eu.portal.klarna.com for Europe, playground.us.portal.klarna.com for North America and Oceania.

Test mode: Use the Klarna playground (test credentials, no real payments). Default: on. While test mode is on, the checkout shows TEST MODE: Klarna playground, no real payment is made. Orders keep the environment they were placed in: captures and refunds of playground orders always use the test credentials.

API region: the region of your Klarna merchant account. Customers can pay with Klarna only from the countries of this region, in the currency of their country.

Europe: Austria, Belgium, Finland, France, Germany, Greece, Ireland, Italy, Netherlands, Portugal, Slovakia and Spain (EUR), Sweden (SEK), Norway (NOK), Denmark (DKK), United Kingdom (GBP), Switzerland (CHF), Poland (PLN), Czech Republic (CZK), Hungary (HUF), Romania (RON). Default.

North America (US, CA, MX): United States (USD), Canada (CAD), Mexico (MXN).

Oceania (AU, NZ): Australia (AUD), New Zealand (NZD).

Live username (UID): the production API username, for example PK12345_abcdef012345.

Live password: the production API password (shared secret).

Test username (UID): the playground API username.

Test password: the playground API password (shared secret).

Order management

A placed Klarna order is an authorization: the customer is charged only when the order is captured. Uncaptured authorizations expire, usually after 28 days, so complete (ship) orders in time or use auto capture.

Capture: when the customer is charged. Refunds are possible only for captured amounts. If a capture fails, the order is put on hold with a note.

When the order is Completed (recommended): capture when you ship by marking the order Completed (default). The amount captured is the order total minus what was already captured, and not more than the amount still authorized.

Immediately (auto capture): charges the customer right away, for digital goods or services.

Manually in the Klarna portal: the plugin does not capture. Capture the order in the Klarna Merchant Portal.

Cancellation: Cancel the Klarna order (release the authorization) when a not yet captured order is Cancelled. Default: on.

Notifications

Klarna reports the result of a fraud review (orders placed as "pending") to the notification URL shown in this section. It looks like https://your-site/wc-api/wc_kl_payment/. The URL is sent with every order automatically, so there is nothing to configure in Klarna. The notification body is never trusted: each notification is verified with the Klarna Order Management API, and the Klarna order must refer to this shop order. The plugin acts on what Klarna reports:

ACCEPTED: Klarna accepted the purchase. The order is marked paid after the amount and currency check.

REJECTED or STOPPED: the purchase did not pass the fraud review. The order becomes Failed.

Klarna order CANCELLED, EXPIRED or CLOSED: the customer was not charged. The order is cancelled.

If Klarna accepts a purchase after you cancelled or refunded the order, the order is not reopened and the Klarna authorization is released.

Advanced

Debug log: Log API calls and payment events in WooCommerce > Status > Logs, source wcp_klarna_payment. Errors are always logged. Logs never contain credentials or customer data. Default: off.

Uninstall: Delete the plugin settings and logs when the plugin is deleted. Order data (Klarna order IDs) is always kept. Default: off.

Checkout

The customer chooses the payment method (by default Klarna) and the Klarna widget loads inside the checkout. There the customer picks pay now, pay later or instalments, as Klarna offers them. When the customer clicks "Place order", Klarna authorizes the purchase in the widget. In the Checkout block the Klarna session is first updated with the final cart, so later changes of shipping or totals do not make Klarna reject the order. The plugin then places the Klarna order server-side with the order lines, totals and addresses of the WooCommerce order.

The result depends on the Klarna fraud status:

ACCEPTED: the order is marked paid at once and the customer goes to the order received page. The money is authorized, and it is captured according to Capture.

PENDING: the order is put on hold until Klarna's notification arrives. Do not ship it before.

REJECTED: the order becomes Failed and the customer sees Klarna could not approve this purchase. Please choose another payment method.

If Klarna cannot accept the order, the customer sees a short message, for example Klarna could not accept this order. Please check your billing details or choose another payment method., Klarna did not respond. Please try again in a moment. or, when the authorization has expired, a request to click "Place order" again. The details are added to the order notes and the log. If the customer's billing country and currency do not match a Klarna market of your region, the customer sees Klarna is not available for your billing country and currency. Please choose another payment method.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin has no Klarna Checkout (KCO, full checkout replacement), Klarna Express Checkout buttons, On-site messaging or Sign in with Klarna, no subscriptions or saved payment methods, and no partial captures per order line. Order lines are not sent to Klarna again when you edit an order after it was placed.

Orders and refunds

Order statuses

Processing or Completed: Klarna accepted the purchase. WooCommerce sets the usual status for a paid order. The order note shows the Klarna order ID and when it will be captured. The transaction ID is the Klarna order ID. When the order is captured, a note shows the captured amount and the capture ID.

On hold: the purchase is pending fraud review, Klarna returned an unexpected fraud status, the amount or currency reported by Klarna did not match the order, or a capture failed. The order notes tell which.

Failed: Klarna rejected the purchase or stopped it after the fraud review. Do not ship the order.

Cancelled: you cancelled the order, or Klarna reports the Klarna order as cancelled, expired or closed. With Cancellation on, cancelling a not yet captured order cancels the Klarna order and releases the authorization, so the customer is not charged. An order that is already captured is not cancelled at Klarna: refund it to return the money.

Capture

With When the order is Completed, marking the order Completed captures the order total. If the capture fails, for example because the order total grew above the authorized amount after you edited it, the order is put on hold with a note that the customer has NOT been charged, and the customer does not get the "Completed order" e-mail. Fix the problem and mark the order Completed again to retry, or capture in the Klarna Merchant Portal.

Refunds

Open the order, click Refund, enter the amount and click Refund via Klarna Payments. Full and partial refunds are supported for captured amounts, up to the captured amount minus what was already refunded. The refund is sent to the environment and region the order was placed in, so the credentials of that environment must be set. If Klarna does not accept the refund, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the Klarna refund ID. A retried refund is never made twice.

An order that was not captured yet cannot be refunded: cancel it instead to release the authorization. Refunds made in the Klarna Merchant Portal are not synchronised back to WooCommerce.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Klarna Payments. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Klarna is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: notifications are still processed, and captures, cancellations and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Klarna does not appear at checkout: check that the license is active, Enable/Disable is on and the credentials of the active mode are filled in: test username and password in test mode, live ones in live mode. The customer's billing country must be a Klarna country of your API region, paying in that country's currency (for example a customer from Sweden must pay in SEK).

The payment went through, but the order stays On hold: the purchase is pending Klarna's fraud review, and the order is updated when Klarna's notification arrives. Check that your site can receive requests from Klarna at the notification URL shown in the settings, and that the credentials of the environment the order was placed in are still entered. Look at WooCommerce > Status > Logs, source wcp_klarna_payment.

Notification answers Not configured: the credentials of the environment (test or live) the order was placed in are missing, so the notification cannot be verified. Enter them.

Notification answers Verification failed: the Klarna order could not be read from the Order Management API. Klarna retries the notification.

Notification answers mismatch_ref: the Klarna order does not refer to this shop order. The order is not changed.

The widget does not load: the customer sees Klarna could not be loaded. Please try again or choose another payment method. or Klarna is not available for this purchase. Check the credentials of the active mode and the customer's country and currency.

Capture failed, order On hold: read the order note. The order total may need more than is still authorized, the Klarna order may not be accepted yet, or the authorization may have expired. Fix it and mark the order Completed again, or capture in the Klarna Merchant Portal.

Refund fails: read the message. The order may not be captured yet (cancel it instead), the amount may exceed what is still refundable, or the credentials of the order's environment may be missing.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

Uninstall

Deactivating the plugin keeps all data. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin are always removed. The gateway settings and the logs (source wcp_klarna_payment) are removed only if Uninstall (Delete the plugin settings and logs when the plugin is deleted) was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Klarna is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Klarna.