VibeFox Klarna for Adobe Commerce — Yardım

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL extension.

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.

Currency: a Klarna currency of your region as the order currency: 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. The order currency is the currency the customer sees in the store; it can differ from the base currency.

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

Installation

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-klarna-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/KlarnaPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_KlarnaPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open VibeFox Klarna Payments. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Choose the API region of your Klarna merchant account, enter the test username and password from the Klarna playground portal, keep Test mode = Yes, set Enable to Yes, click Save Config and place a test order. Then enter the live username and password from the Klarna Merchant Portal, set Test mode to No and choose when orders are captured (default: when the order is shipped).

The module adds the Klarna payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates tables for the Klarna orders, refunds and temporary widget sessions.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > VibeFox Klarna Payments, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove data on uninstall is read from the Default Config only. Save Config saves the whole page. Amounts accept "9.99" and "9,99".

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort order that is not a whole number; a Minimum order total or Maximum order total that is not a number of 0 or greater; an unknown API region or Capture value.

General

Enable: shows or hides Klarna at checkout. It is shown only when the username and password of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Klarna. Required, at most 128 characters.

Description: the text shown above the Klarna widget when the customer selects the payment method. Default: Pay now, later or in instalments with Klarna.

Sort order: the position among the payment methods at checkout. A whole number. Default: 0.

API credentials

The section explains: Create API username and password in Klarna Merchant Portal > Settings > Klarna API credentials. Use the playground portal for test credentials. Test credentials come from the Klarna playground portal of your region.

Test mode: uses the Klarna playground (test credentials, no real payments). Default: Yes. Set it to No to take real payments. 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. The country is taken from the billing address (or from the shipping address when the billing address has no country yet).

Live username (UID): the production API username.

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

Clear saved live password: set it to Yes and click Save Config to delete the saved live password. It goes back to No after saving.

Test username (UID): the playground API username.

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

Clear saved test password: the same for the test password.

Magento stores the passwords encrypted and shows only a mask (******) after saving. Leave the mask or an empty field as it is to keep the saved password, type a new value to change it. An empty field never deletes a password: use the Clear saved … setting for that.

Notifications: shows the Notification URL, for example https://your-store/wcpklarnapayment/notification/index. Klarna reports the result of a fraud review (orders placed as "pending") to this address. The module sends the storefront URL with every Klarna session and order automatically, so there is nothing to configure in Klarna. The notification body is never trusted: Klarna sends fraud review notifications automatically. Each notification is verified with Order Management API; no signature secret is required. The module reads the Klarna order with the credentials of the environment and region the order was placed in, and the Klarna order must refer to this store's cart and order number.

When Enable is Yes, this section also shows TEST MODE: Klarna playground, no real payments. while test mode is on, and Enter the username and password of the selected Klarna environment. when the credentials of the current mode are missing (Klarna is then hidden at checkout).

Order management

An accepted Klarna order is an authorization: the customer is charged only when the order is captured. Uncaptured authorizations expire at Klarna, so ship orders in time or use auto capture.

Capture: when the customer is charged. Refunds are possible only for captured amounts.

Cancellation: when Yes, cancelling a not yet captured order in Magento cancels the Klarna order and releases the authorization, so the customer is not charged. Default: Yes.

Payment from applicable countries: All Allowed Countries offers Klarna for every country your store allows, Specific Countries only for the countries below. Klarna itself is offered only in the countries of your API region.

Payment from Specific Countries: offer Klarna only for billing addresses in these countries.

Minimum order total: offer Klarna only from this order total, in the base currency of your store. Default: 0.

Maximum order total: offer Klarna only up to this order total, in the base currency. Empty means no maximum.

Advanced

Debug log: writes Klarna requests and payment events to var/log/wc_kl_debug.log.php in the Magento folder. The file cannot be opened from the web. Errors and warnings are always written. Credentials, tokens and customer contacts are removed from the entries, and request bodies are not logged. Default: No.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Remove data on uninstall: when Yes, uninstalling the module with its data deletes the module settings, the log and the temporary widget sessions (see Uninstall). The license key is always removed. The Klarna orders and refunds always stay. Default: No.

Checkout

At the payment step the customer chooses the payment method (by default Klarna) and sees the description and the button Load Klarna. The button creates the Klarna session from the cart on the server and loads the Klarna widget inside the payment step; the customer chooses how to pay among the options Klarna shows. Place Order becomes active when the widget is loaded. If the cart totals or the billing address change, the customer loads Klarna again. On Place Order Klarna authorizes the purchase in the widget. If Klarna does not approve it, the customer stays at checkout with Klarna could not approve this purchase. Please try again or choose another payment method. and no order is placed.

After the authorization Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module checks that the order still matches the authorized cart and places the Klarna order server-side with the order lines, totals and addresses, in the order currency. The Klarna order carries the cart ID and the order number as merchant references. The result depends on the Klarna fraud status:

If Klarna refuses the authorization, the cart changed after the authorization, or the customer's country and currency do not match a Klarna market of your region, the order is cancelled, the cart is restored and the customer sees a short message in the cart, for example Klarna could not accept this authorization. Please authorize again., Klarna authorization is missing or the cart changed. Please authorize again. or Klarna is not available for your billing country and currency.

If Klarna does not answer, or the answer has no valid Klarna order ID, the module cannot know whether the purchase was placed. The order stays in Pending Payment and the customer sees, for example, Klarna did not confirm the result. Do not pay again; contact the store. Check the order in the Klarna Merchant Portal (search for the order number). A repeated attempt for the same order never places a second Klarna order: the customer sees Your Klarna purchase needs manual verification. Do not pay again. Clicking twice never places a second Klarna order for the same cart either.

If Klarna returns the customer to the store through the confirmation link of the order, the module checks the Klarna order again and the customer lands on the home page with Your Klarna order status has been checked. Please see your order or contact the store. The link does not show the order.

The module works with the standard Magento checkout. It 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. Order lines are not sent to Klarna again when an order is changed after it was placed. Klarna is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and Klarna has not accepted the purchase yet: the fraud review is pending, or the result of placing the Klarna order is unknown. There is no invoice. Magento cancels orders that stay in Pending Payment longer than the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings); with Cancellation = Yes this also cancels the Klarna order.

Processing: Klarna accepted the purchase. The payment is recorded as an authorization with the Klarna order ID, and a note says Klarna authorization accepted. with the captured amount. The invoice is created when the order is captured.

On Hold: Klarna returned an unexpected fraud status, or the amount or currency reported by Klarna did not match the order (note Klarna amount/currency mismatch. Held for review, no invoice.). Check the order in the Klarna Merchant Portal.

Canceled: Klarna rejected the purchase, the Klarna order could not be placed, or the order was cancelled in Magento. A Klarna notification that arrives for a cancelled or closed order only adds a note; the order is not reopened.

Complete or Closed: the standard Magento states after shipment and invoice, or after a full refund.

The notes are order comments that the customer does not see.

Capture

With When the order is shipped, creating the first shipment captures the order total at Klarna before the shipment is saved, and Magento creates the paid invoice with the Klarna capture. If Klarna refuses the capture, for example because the authorization expired or the Klarna order is not accepted yet, Magento shows the error and the shipment is not saved: the customer has NOT been charged. Fix the problem and create the shipment again, or capture in the Klarna Merchant Portal.

In every mode you can also capture from Magento: create an invoice and choose Capture Online. Partial invoices capture their amount, up to the amount still authorized; the amount is sent in the order currency. If Klarna refuses, the invoice is not created.

A capture made in the Klarna Merchant Portal needs a matching invoice in Magento: create it with Capture Offline, so that the order shows the amount as paid. Refund such amounts in the Klarna Merchant Portal and record them with Refund Offline. When the module reads the Klarna order later (for example on a Klarna notification) and finds a partial capture made in the portal, it adds the note Klarna partial capture in portal; reconcile invoices manually.

Cancellation

With Cancellation = Yes, cancelling an order that is not captured yet (Cancel or Void on the order page) cancels the Klarna order and releases the authorization. An order that is already captured cannot be cancelled at Klarna: refund it to return the money. If Klarna cannot be reached, the order gets the note Klarna authorization could not be cancelled. Check Merchant Portal.

Klarna payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and Klarna order ID, Environment, API region, Klarna state, Authorized amount, Captured amount and Refund history. The customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Klarna. Full and partial refunds are supported, in the order currency, up to what Klarna reports as captured minus already refunded. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Klarna.

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, Magento shows the error and the credit memo is not created. After a successful refund Magento records it with the Klarna refund ID as the transaction ID, and the refund is added to Refund history. A full refund closes the order. A retried credit memo is never refunded twice. An order that was not captured yet has no invoice and cannot be refunded: cancel it instead.

Refunds made in the Klarna Merchant Portal are not added to the order. They count toward the amount Klarna still allows to refund. Create a credit memo with Refund Offline if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Klarna Payments is the first row of the VibeFox Klarna Payments group in Stores > Configuration > Sales > Payment Methods, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this store. Below them are the line Product: magento-payment-klarna and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. Removing the key from the store 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, and the widget cannot be loaded. If a payment is started anyway, the order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: Klarna notifications are still processed, and orders can still be captured, cancelled and refunded.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Klarna does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that the username and password of the current mode are filled in: test ones with Test mode = Yes, live ones with No. The API credentials section shows a warning when they are missing. 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), and the order total must be above zero. Check Payment from applicable countries, Payment from Specific Countries, Minimum order total and Maximum order total.

The purchase was accepted, but the order stays Pending Payment: the purchase is pending Klarna's fraud review, and the order is updated when Klarna's notification arrives. Check that your store can receive requests from Klarna at the Notification URL, and that the credentials of the environment the order was placed in are still entered. Turn on Debug log and look at the Log field. If the customer saw Do not pay again, check the order in the Klarna Merchant Portal.

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. Klarna retries the notification.

Notification answers Verification failed or Retry: the Klarna order could not be read from the Order Management API, or the order was being updated by another request at the same moment. Klarna retries the notification.

Notification answers mismatch_ref or Unknown order: the Klarna order does not refer to this store's cart and order number, or the module does not know it. The order is not changed.

The notification URL shows Method not allowed in the browser: this is normal. The URL accepts only requests from Klarna.

Notifications fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the notification URL too. Klarna retries the notification later.

A pending order was cancelled by Magento: the fraud review took longer than the Pending Payment Order Lifetime. Increase it in Stores > Configuration > Sales > Sales > Orders Cron Settings if Klarna reviews often take longer.

The widget does not load: the customer sees Klarna could not be loaded. Please try again., Klarna is unavailable. Please reload checkout. or Klarna is not available for this purchase. Check the credentials of the current mode and the customer's country and currency.

Creating the shipment is refused: the Klarna capture failed. Read the error, for example Klarna capture exceeds the remaining authorization. or Klarna capture failed. Check Merchant Portal and retry the same operation. The Klarna order may not be accepted yet, or the authorization may have expired. Fix it and create the shipment again, or capture in the Klarna Merchant Portal.

Refund fails: read the message, for example Klarna refund exceeds captured minus refunded. The amount may exceed what is still refundable, or the credentials of the order's environment may be missing.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice is not captured yet and cannot be refunded; cancel it instead.

The customer sees Klarna checkout is busy: another request for the same cart is running, for example a double click. Wait a moment and check whether the order was created.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_KlarnaPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_KlarnaPayment to remove the data, then bin/magento module:disable Vibefox_KlarnaPayment, delete the folder app/code/Vibefox/KlarnaPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. If Remove data on uninstall is Yes, the module settings, the log and the temporary widget sessions are removed too. If it is No, the settings are kept for a re-install. The Klarna orders and refunds are always kept, so orders placed before can still be captured and refunded after a re-install. Existing orders keep their invoices, payment notes and transaction IDs.

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