VibeFox Klarna for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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.

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 the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Klarna Payments in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

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

6. Enter the live username and password from the Klarna Merchant Portal, turn off Test mode and choose when orders are captured (default: when the order is shipped).

On install the module creates two order statuses, Awaiting Klarna fraud review and Klarna payment on hold. Neither of them counts as paid or sends an e-mail. PrestaShop offers a new payment module for all currencies, countries and customer groups. You can limit them in Payment > Preferences.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Klarna Payments > Configure. Each section has its own Save button, which saves the whole page. Above the fields the page shows TEST MODE: Klarna playground, no real payments. or LIVE: real Klarna payments. It warns you when the username or password of the active mode is missing (Klarna is then hidden at checkout) and when the default currency of the shop is not sold by Klarna in the selected API region.

Klarna Payments

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

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

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: uses the Klarna playground (test credentials, no real payments). Default: on. While test mode is on, customers see TEST MODE: Klarna playground, no real payment is made. under the payment method. 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 invoice address of the cart.

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).

Saved passwords are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved passwords: tick a password and click Save to remove it. An empty field keeps the saved value.

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 ship orders in time or use auto capture.

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

When the order is shipped (recommended): capture when you set the order to a shipped status, such as Shipped or Delivered (default). The amount captured is the order total minus what was already captured, and not more than the amount still authorized. If the capture fails, the status is not changed and the reason is shown on the order page.

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

Manually in the Klarna portal: the module 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 address shown in Notification URL. With friendly URLs it looks like https://your-shop/module/wcp_klarna_payment/notification, possibly with a language code such as /en/. 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, with the credentials of the environment and region the order was placed in, and the Klarna order must refer to this shop's cart. The module 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 Payment error.

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. The notification works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

Advanced

Debug log: logs API calls and payment events to logs/wc_kl_debug.log.php in the module folder. The file cannot be opened from the web. Errors are always logged. The log never contains credentials, authorization tokens or customer data. Default: off.

Log: shows the size and the latest entries of the log, with a button to clear it.

Uninstall: delete the module settings and the log when the module is uninstalled. Order data (Klarna order IDs, refunds) is always kept. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Klarna, with the Klarna badge) and the Klarna widget loads inside the payment step. The module creates the Klarna session from the cart on the server. In the widget the customer picks pay now, pay later or instalments, as Klarna offers them. When the customer places the order, the Klarna session is first updated with the final cart, and Klarna authorizes the purchase in the widget. The module then places the Klarna order server-side with the order lines, totals and addresses of the cart. Cart discounts are sent to Klarna as a separate line. No order exists before Klarna answers.

The result depends on the Klarna fraud status:

ACCEPTED: the order is created as Payment accepted and the customer sees the standard order confirmation page. The money is authorized, and it is captured according to Capture.

PENDING: the order is created as Awaiting Klarna fraud review until Klarna's notification arrives. Do not ship it before.

REJECTED: no order is created. The customer stays at checkout with Klarna could not approve this purchase. Please choose another payment method.

If Klarna cannot accept the order, the customer stays at checkout with 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 written to the log. If the customer's 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.

Clicking twice never places a second Klarna order for the same cart. If the cart changes while Klarna answers, for example in another browser tab, the order is created as Klarna payment on hold with a note. If Klarna approved the purchase but the order could not be created, the customer sees Your Klarna purchase was approved, but the order could not be completed automatically. Please contact us — do not pay again. The next attempt or Klarna's notification creates the order from the stored Klarna order without a new authorization.

The Klarna order in the Klarna Merchant Portal carries the cart number as the merchant reference, because the PrestaShop order does not exist yet when it is placed.

The module 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

No order yet: the customer has not completed the Klarna authorization, or Klarna rejected the purchase. Only the cart exists.

Payment accepted: Klarna accepted the purchase. The payment is recorded with the Klarna order ID as the transaction ID, and a private note shows the Klarna order ID and when it will be captured.

Awaiting Klarna fraud review: the purchase is pending Klarna's fraud review. Klarna's notification moves the order to Payment accepted, Payment error or Canceled.

Klarna payment on hold: Klarna returned an unexpected fraud status, or the amount or currency reported by Klarna did not match the order. The note explains it. Check the order in the Klarna Merchant Portal.

Payment error: Klarna rejected or stopped the purchase after the fraud review. Do not ship the order.

Canceled: 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.

Refunded: the captured amount was fully refunded through the module.

Capture

With When the order is shipped, setting the order to a shipped status captures the order total before the new status is saved. If Klarna refuses the capture, for example because the order total grew above the authorized amount after you edited it, the status is not changed, no e-mail is sent and the reason is shown on the order page and in a note: the customer has NOT been charged. Fix the problem and change the status again to retry, or capture in the Klarna Merchant Portal and switch Capture to manual. On PrestaShop 8 in production mode the back office may write the status anyway; the module then sets Klarna payment on hold instead, with a note, so the order is never shown as shipped without the capture. A successful capture adds a note with the captured amount and the capture ID.

Klarna payment block

The order page shows a Klarna payment block with the Klarna order ID, its environment and region, a Playground badge for test orders, the fraud status and Klarna status, the authorized amount, the captured and refunded amounts and the refund history.

Refunds

In the Klarna payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Klarna. Confirm the question Refund this amount through Klarna? This cannot be undone. Full and partial refunds are supported for captured amounts, up to what Klarna reports as captured minus already refunded. You need the right to edit orders; access to the modules is not needed. 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, the block shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the Klarna refund ID. A full refund sets the order to Refunded; a partial refund does not change the status. A retried refund is never made twice.

An order that was not captured yet cannot be refunded: cancel it instead to release the authorization. With Capture set to manual the shop does not know what you captured in the Klarna Merchant Portal. The refund form is then shown with an empty amount, and Klarna checks the amount when you submit it.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Klarna. Refunds made in the Klarna Merchant Portal are not added to the block, but they count toward the amount Klarna still allows to refund.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Klarna Payments is the first block on Modules > Module Manager > VibeFox Klarna Payments > Configure, 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 shop. Below them are the line Product: presta-payment-klarna and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (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 shop 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 main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, 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 Modules > Module Manager on the Alerts tab. 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 while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 settings page shows a warning when they are missing. The customer's invoice 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). In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group.

The payment went through, but the order stays Awaiting Klarna fraud review: the purchase is pending Klarna's fraud review, and the order is updated when Klarna's notification arrives. Check that your shop 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. Turn on Debug log and look at the Log field on the module page.

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: the Klarna order could not be read from the Order Management API. Klarna retries the notification.

Notification answers Busy: 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 shop's cart, or the module does not know it. 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.

The status change to Shipped is refused: the Klarna capture failed. Read the reason in the Klarna payment block or the 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 change the status again, or capture in the Klarna Merchant Portal.

Refund fails: read the message in the block. 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 customer sees This order is already being paid: another request for the same cart is running, for example a double click. Wait a moment and check whether the order was created.

Uninstall

Go to Modules > Module Manager, open the menu next to VibeFox Klarna Payments and choose Uninstall. The license key and license status of this module are always removed. If Uninstall is on in the Advanced section, the module settings, the log and the temporary widget sessions are removed. If it is off, all settings are kept for a later re-install. The Klarna orders and refunds and the order statuses Awaiting Klarna fraud review and Klarna payment on hold are always kept, so orders placed before can still be captured and refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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