Klarna Payments on Shopify - Merchant Guide

Table of Contents

Installing Klarna Payments on Shopify 4 1. Install the Klarna Payments private app in your Shopify store 4 2. Enter your Klarna API credentials 5 3. Activate your Klarna alternative payment method(s) 6 Klarna On-Site Messaging app for Shopify 7 Useful links 7 Troubleshooting 7

Shopify admin features relating to Klarna Payments 9 Phone number 9 Why does Klarna Payments require a Shopify app 9 Shopify Draft Orders (and the Klarna Seller’s App) 10 Multi-Currency 10 When should a merchant use Test Mode? 12

Shopify Plus: custom scripts 12 Hide Klarna payment methods based on Cart presentment currency 12 Hide Klarna payment methods based on Product SKUs 13 Hide Klarna payment methods based on Product Tags 13

Order Management 14 Pending Orders 14

Pending - Awaiting Fraud Decision 14 Pending - Accepted 14 Pending - Rejected 15 Pending - Stopped 15

Cancel an order 15 Fulfill an order 16 Partial fulfillments 17 Refund an order 18

Updating the Klarna Payments configuration 18 General Settings 20 Template Settings 20

Locale 20

Known Issues 22

Klarna Payments accepts orders only for customer billing addresses in the markets that match the store base currency 22 Updating Klarna API credentials severs communication for previously placed orders 23 Refunds stuck in pending for orders older than 60 days 24 Editing Klarna orders in Shopify admin not yet supported 24

Installing Klarna Payments on Shopify In order to go live with Klarna Payments on Shopify, you first need Klarna API credentials. If you don’t yet have Klarna API credentials, you can sign up via klarna.com

1. Install the Klarna Payments private app in your Shopify store

● Run the Klarna Payments Shopify setup wizard, using this URL: https://www.klarnapayments.com/install

● Under “Install Klarna Payments App” tab, enter your store domain in the textbox, and hit the pink button, which initiates the install of the private Klarna Payments app:

● This will take you to your Shopify store or log in page if you are not logged in already. There you’ll see a page informing you that you’re about to install Klarna payments. Click Install unlisted app.

2. Enter your Klarna API credentials

● You’re now redirected back to the previous page to continue the integration. Under “Authenticate Klarna API Credentials”, enter your live Klarna API credentials. Do not use Test mode if your store is live, as Klarna will not pay out for test orders.

● Your credentials are now checked, and authentication results are displayed. Note: Klarna credentials work for either test or production environment, but not both environments.

● Go back to your Shopify store admin page.

3. Activate your Klarna alternative payment method(s)

● On your Shopify admin page, go to Settings in the bottom left corner.

● Go to “Payment providers”, and scroll down to “Alternative payments”.

● Select your Klarna payment alternative payment method(s) and enter your Klarna credentials. After activating the alternative payment method(s), Klarna will display as a payment option in your Shopify checkout. (Only check test mode if you checked use test mode in the wizard. Klarna recommends that you only activate an alternative payment method in test mode for a test store or a store that is not yet live to customers. For more details, see “When should a merchant use Test Mode?”) Note: the Klarna API credentials entered in your Shopify admin must match the credentials entered in the 2nd tab of the setup wizard in order for the Klarna Payments page to display without error.

Klarna Payments is now live as a payment method in your store’s checkout!

To verify the integration, add a product to your cart, navigate through your Shopify checkout, select the Klarna Payments option(s) in the Shopify payment method page, and after clicking the “Complete Order” button (or after the Review Order page, if configured for your store), make sure the Klarna Payments hosted page loads successfully. (Do not actually place the order from this page if using live Klarna credentials.)

Klarna On-Site Messaging app for Shopify

Klarna offers an app on the Shopify app store to enable you to easily promote Klarna on your store. The app can be installed from https://apps.shopify.com/klarna-on-site-messaging Additional details about the app available at: Klarna On-Site Messaging app on Shopify - Support Guide

Useful links

● A sample install video can be seen at Klarna Payments on Shopify Install Video.

● A sample customer experience can be seen at Klarna Payments on Shopify Customer Experience Video and also live at https://klarnastore.myshopify.com/.

Troubleshooting

If the Klarna Payments page does not load successfully, please check the following. Please also review the Logs within the Klarna Merchant Portal to check for error codes & messages.

1. There is a small time delay for new Klarna credentials to propagate through all the required systems. Try testing again after about 20 -90 minutes. (error code: 403, error message: INVALID_OPERATION)

2. Please verify your Klarna credentials (username & password) are correctly entered in both the Klarna Payments app configuration and in your Shopify store (under Alternative Payments). We recommend copying & pasting the credentials rather than typing them directly. (error code: 401, error message: UNAUTHORIZED)

3. If you’ve regenerated Klarna credentials, if you update Shopify with new credentials in the alternative payment method configuration, you will also need to update the Klarna Payments app API credentials. Note: as documented in the Known Issues section below, updating the Klarna API credentials can sever communication for previously placed orders, so updating Klarna API credentials is not recommended unless necessary. Both credentials must match for the integration to work successfully. Check the following places:

● the Klarna credentials under Shopify admin → Settings → Payment providers → Alternative payments → all active Klarna alternative payment methods

● Shopify admin → Apps → Klarna Payments (which redirects to the setup wizard)

4. Verify that your Shopify’s configured store currency (in Shopify admin → Settings → General → Store currency) matches the currency you’ve contracted for with Klarna. Klarna Payments does not currently support EU stores selling in USD, but can support EU stores selling in EUR (even if EUR is not the primary currency for the shop’s configured store address, e.g. Norway).(error code: 400, error message: Bad value: purchase_currency)

5. If the Klarna Payments page is still not loading successfully, please contact Klarna Merchant Support.

Shopify admin features relating to Klarna Payments

Phone number

By default, phone number is optional in Shopify checkout, but Klarna Payments requires that both phone and email are entered. If the phone number or email is not provided to Klarna on redirect, the consumer will be given an error message and redirected back to the Shopify checkout. To avoid errors and provide a streamlined consumer experience, we recommend setting phone number as required in Shopify admin by navigating to Settings → Checkout → Form options:

Under Shopify admin → Settings → Checkout → Customer contact, we recommend choosing the “Customers can only check out using email”.

Why does Klarna Payments require a Shopify app

The app is needed to support the data needs of the payment method as well as the back end integration. Shopify, by default, only transmits the billing/shipping information and cart value in the redirect request to the payment method provider. For Klarna to make the best possible decisions for offering payment terms, the order line item data is also needed. Shopify restricts payment processing apps to be private apps, so the Klarna Payments app is not publicly available in the Shopify app store. This app is required and installed during the flow from www.klarnapayments.com/install

Shopify Draft Orders (and the Klarna Seller’s App)

If using Shopify draft orders for in-store customers, Klarna recommends adding a 0 value product named “Ship to store”, which should be set as not available for your sales channels, as shown in the screen shot below. When creating Shopify draft orders, add the “Ship to store” product to the customer’s order to trigger the Klarna Payments fraud review logic for in-store customers.

If the “Ship to store” product is not included in the order, Klarna orders could get Pended for fraud review, which is not desired for in-store orders. Klarna’s order management will work for these Shopify draft orders when the order is fulfilled, cancelled, or refunded in the Shopify store admin (since the order uses the same Klarna Payments alternative payment method as online orders). Note: Klarna orders created via the Klarna Seller’s App in the Klarna Merchant Portal also trigger the in-store fraud review flow, but these orders require additional order management; the order must be fulfilled, cancelled, or refunded both in the Shopify store admin and in the Klarna Merchant Portal. Since these orders do not use the same Klarna Payments alternative payment method as online orders, the code is not triggered to update Klarna when the Shopify order is updated. (Order management for Shopify orders is processed based on the configuration of the payment method used for the order.)

Multi-Currency

Shopify restricts all alternative payment methods, such as Klarna Payments, to only process orders in the store’s base currency, as documented at: https://help.shopify.com/en/manual/payments/shopify-payments/multi-currency/conversions#shopify-payments-and-other-payment-providers

“Only Shopify Payments can process payments in a customer's local (presentment) currency. If your customer chooses a payment option from a different payment provider, then their payment is made in the currency of your store.”

See also Known Issue: “Klarna Payments accepts orders only for customer billing addresses in the markets that match the store base currency”. Shopify supports multi-currency for Shopify Payments orders for all Shopify stores, as documented at https://help.shopify.com/en/manual/payments/multi-currency. As long as the Klarna Payments app in the Shopify store is up to date (to have the necessary read_checkouts scope to process multi-currency data), Shopify will convert the order to store’s base currency, if the order is not already in that currency. If the app does not have the required scope, customers may receive an error page after choosing Klarna when the customer’s presentment currency is different than the Shopify’s store base currency. To verify that the Klarna Payments app is up to date with the required read_checkouts scope, from your Shopify store admin, go to Apps on the left hand menu, and click the Klarna Payments app. If necessary, you will be presented with a screen to update the app, similar to the screen shot example below. Just click the “Update unlisted app” button.

After the app is updated, you will then be redirected to the Klarna Payments app install wizard; no action is required at that page, and the browser tab can be closed.

For Shopify Plus merchants, please also see: “Shopify Plus: custom scripts” section below if you would like to hide Klarna Payments in checkout based on certain cart data.

When should a merchant use Test Mode?

If your Shopify store is a test store or your store is not yet live, and you have Klarna API test credentials, then check Test mode. Klarna recommends that you only activate an alternative payment method in test mode for a test store or a store that is not yet live to customers. If you do have a test store, you will repeat the setup wizard for your live store using production credentials once testing is complete. Test mode should not be used for live stores as Klarna does not pay out for orders made against Test Drive. If production Klarna API credentials are used and test mode is checked for the Shopify payment method, orders will be blocked with an error. If test orders are desired, Klarna API test credentials should be used (but this is not recommended for live stores).

Shopify Plus: custom scripts Shopify Plus merchants can use custom scripts to hide Klarna Payments methods(s) based on certain cart data, as documented below:

1. Go to the Shopify script editor 2. Click Create Script 3. Choose Payment Gateways for the script type 4. Choose Blank Template 5. Click Create Script 6. In the Title box, enter your desired script name 7. Click Code to open the Ruby source code console per examples below 8. Click Run Script 9. Click Save and Publish

Hide Klarna payment methods based on Cart presentment currency

cart = Input.cart available_gateways = Input.payment_gateways if cart.presentment_currency != "USD" available_gateways = available_gateways.delete_if do |payment_gateway| payment_gateway.name == "Buy now, pay later with Klarna" end end Output.payment_gateways = available_gateways

Hide Klarna payment methods based on Product SKUs

available_gateways = Input.payment_gateways cart = Input.cart SKUS_TO_HIDE = ["SKU-1234", "..."] cart.line_items.each do |item| item.variant.skus.each do |sku| if SKUS_TO_HIDE.include? sku available_gateways = available_gateways.delete_if do |payment_gateway| payment_gateway.name == "Buy now, pay later with Klarna" end end end end Output.payment_gateways = available_gateways

Hide Klarna payment methods based on Product Tags

available_gateways = Input.payment_gateways cart = Input.cart TAGS_TO_HIDE = ["hide-klarna", "..."] cart.line_items.each do |item| item.variant.product.tags.each do |tag| if TAGS_TO_HIDE.include? tag available_gateways = available_gateways.delete_if do |payment_gateway| payment_gateway.name == "Buy now, pay later with Klarna" end end end end Output.payment_gateways = available_gateways Note: each store should customize the bolded parts of the above script to use the appropriate data for the store.

Order Management As mentioned above, the Klarna Payments integration provides integrated order management. Order management for Klarna orders should continue to be processed as part of your standard order management processing via Shopify. Klarna orders can be fulfilled, refunded, and/or cancelled in the same way as for other Shopify orders. (While order management could be done directly via the Klarna merchant portal, this will cause Klarna data and Shopify order data to be out of sync. Unless there is an issue, all order management should be done through the Shopify admin, not the Klarna merchant portal.)

Pending Orders

Currently Klarna offers pending functionality, generally used for US & UK markets. With pending, orders are reviewed by Klarna and should not be fulfilled (shipped) by merchants until after Klarna has made the fraud decision. For more information, see developers.klarna.com

Pending - Awaiting Fraud Decision When a Shopify order has been placed by a customer, if the order is awaiting Klarna review, the Shopify order payment status will be Pending, see screenshots below:

Pending - Accepted If a pending fraud order is accepted, the Shopify order payments status will be updated to Paid:

Pending - Rejected

If a pending fraud order is rejected, the Shopify order will be cancelled:

Pending - Stopped

If an order is fraud accepted, but later reviewed and determined to be fraudulent, a fraud stop email will be sent to the merchant. If the Shopify order is not yet fulfilled, the Shopify order will be cancelled, as shown below. Unfortunately once a Shopify order has been marked as Paid, the order payment status cannot be changed.

Cancel an order

To cancel a Klarna Payments order, navigate to the desired order and select the “Cancel” option from the Shopify “More Actions” option at the top right, as shown below. The appropriate data will be sent from Shopify to Klarna and the order will be cancelled in Klarna as well.

Fulfill an order

To fulfill a Klarna Payments order, navigate to the desired order, fill in the appropriate information, and click the “Fulfill items” button. The appropriate data will be sent from Shopify to Klarna and the order will be updated as captured in Klarna accordingly, and Klarna will pay the merchant for the captured amount of the order.

In Shopify Admin, under Settings->Payments, you can set auto-capture payment for orders, but this setting only affects credit card captures. This will not capture orders in Klarna. Orders in Klarna are not captured until the order is fulfilled in Shopify.

If desired, you can configure the setting for auto-fulfill. This setting is found at Settings->Checkout->Order Processing. If set, orders are automatically fulfilled in Shopify and hence also Klarna orders will be auto-captured. Be aware that this will affect all future orders within your Shopify store.

Alternatively, if necessary, merchants can capture Klarna orders directly in the Klarna Merchant Portal, but this action will not update the Shopify order data.

Partial fulfillments

When an order is partially fulfilled, the total shipping charge is captured in Klarna when the first order line item is fulfilled in Shopify. The appropriate percentage of tax is captured with each partial fulfillment according to the line items that are fulfilled. Discounts are included with the final capture.

For example, a customer buys 3 order line items of $49.99 each, tax of $11.24, discount of $14.99, and shipping of $15.00, totaling $161.22. If 1 line item is partially fulfilled, $69.86 is captured ($49.99 line item, $15.00 shipping, & $4.87 tax). When doing the final capture, the discount is applied.

Refund an order

To refund an order, navigate to the order in the Shopify admin tool and choose the Refund option, as shown below.

If an order is refunded prior to fulfillment, the Klarna order will either be cancelled (if full refund) or the chosen refund amount will be reduced from the Klarna authorization amount. If an order is refunded after fulfillment, the Klarna order will be refunded accordingly. Please note that there is a small time delay (around 5 minutes) after the refund is updated in Shopify admin before the update will be reflected on the Klarna order.

Updating the Klarna Payments configuration After completing the Klarna Payments setup wizard per previous steps, it may be necessary in some cases to update the default template settings or update the credentials used to connect to Klarna. In the Klarna Payments app, if desired you can adjust the colors, style and logo of the payment page to look more like your store’s Shopify checkout.

1. To access the Klarna Payments app configuration screen, navigate to the app menu item on the left side of the Shopify admin.

2. Under the installed apps list click the Klarna Payments app link. (If the app requires an update, it will show after clicking the app link.)

3. A new window will launch and show the General Settings tab, where after entering your Klarna credentials, you can also access your store’s Klarna Template Settings for the Klarna Payments page for Shopify.

General Settings If you need to enter new credentials to move from test to production, you can do so here by entering the credentials and toggling the test mode check box.

Template Settings These settings will apply to the hosted payment page where the customer is redirected from Shopify checkout after selecting the Klarna Payments option. Changing the options below will change elements of the page as well as the Klarna application. For more details on how the below options affect the Klarna application see the developer site page, Customizing The Klarna Form. All URLs in the HPP template should be HTTPS URLs (not HTTP URLs); otherwise the HPP page for the store will have a security error and customers may receive security errors when opening the page (depending on their browser settings).

1. Locale As selected as the default option for this field for most merchants, Klarna recommends to use the “Locale set to customer selection” option, as this most closely aligns with locale processing within the Klarna Payments iframe, as documented at: https://developers.klarna.com/documentation/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/ The code for this ShopifyHPP Klarna Payments integration pulls the customer’s locale from the Shopify’s checkout API data. If the customer’s locale is supported by this integration, it will be honored, but if the locale is not available, English will be used instead.

Alternatively, merchants can force a locale for the Klarna Hosted Payments page to either a specific locale (e.g. sv-se) or “Locale set to merchant's Klarna setting for purchase_country” (e.g. for a merchant with purchase_country=no, locale would be nb-no), but with any of these locale options other than “Locale set to customer selection”, be aware that the Klarna Payments iframe may not honor the requested locale based on customer’s billing address and then the language within the Klarna Payments iframe may not match the language outside the iframe.

2. Page Title

● Defaulted to “Checkout - [store name]”

● Can be updated to any desired text

3. Favicon

● Defaulted to favicon url found in Shopify

● If not found, it will be blank.

● Can be updated to a favicon image hosted elsewhere

4. Store Logo

● Klarna will upload the store’s logo to the Klarna CDN. This logo image file must meet the following criteria:

○ PNG format with a transparent background

○ No grey or white as predominant colors

○ No padding added to the logo

○ Between 300px and 1024px wide, larger logos display better than smaller

● The store logo will be defaulted to link to the logo that has been uploaded to the Klarna CDN

● Can be updated to a logo hosted elsewhere

5. Footer text

● Defaulted to footer text found in the store checkout.

● If no default is found, will be blank

● Can be updated to any desired text

6. Colors

● All colors supported by the Klarna Payments integration are available to be configured.

● Color button

● Also used for the “Place Order” button outside of the iframe

● Color link

○ Also used for “Change Payment Method” link outside of the iframe, which goes back to Shopify checkout page

● Color border

● Color border selected

● Color text

● Color details

Known Issues

1. Klarna Payments accepts orders only for customer billing addresses in the markets that match the store base currency

Klarna Payments accepts orders only for customers with billing addresses in the markets that match the currency of the order, per: https://developers.klarna.com/documentation/klarna-payments/in-depth-knowledge/puchase-countries-currencies-locales/. Since Klarna Payments integration is an alternative payment provider in Shopify, Shopify limits Klarna Payments, and all alternative payments methods, to always using only the store’s base currency, see: https://help.shopify.com/en/manual/payments/shopify-payments/multi-currency/conversions#shopify-payments-and-other-payment-providers. As such, if the store base currency is SEK, Klarna Payments will be able to accept orders for customers whose billing country is Sweden. Customers will addresses in other countries will receive an error message stating “Not available for this country”, as shown in the screen shot below:

2. Updating Klarna API credentials severs communication for previously placed orders

In the Klarna Merchant Portal Settings app, merchants can generate new Klarna API credentials and/or disable previous API credentials, as shown below:

Changing Klarna API credentials for the Klarna Payments Shopify integration should only be done if necessary (i.e. security breach). If changing API credentials are necessary, updated credentials must be changed both via the Klarna Payments app (under Apps in your Shopify store) and in the Klarna payment method(s) (under Settings->Payment providers in your Shopify store). You should also verify and update any previously placed Klarna orders in the Klarna Merchant Portal, as needed. Pending status notifications from Klarna will not be able to update previously placed orders in the Shopify store; those orders will stay stuck in Pending status.

3. Refunds stuck in pending for orders older than 60 days

This issue is applicable for stores that installed Klarna Payments prior to July 2018. Refunds older than 60 days require the read_all_orders scope, as noted at https://help.shopify.com/en/api/reference/orders/order. If some refunds are stuck in pending in your Shopify store and the order is older than 60 days, please make sure that the Klarna Payments app is up to date in your Shopify store to be able to access orders older than 60 days. To do so, a Shopify admin user with full admin permissions to the Shopify store, within the Shopify admin web page, can go to the Apps menu on the left hand side and click the "Klarna Payments" app. If the Klarna Payments app doesn’t have the necessary permissions, a web page will be presented stating "You are about to update Klarna Payments". After clicking "Update unlisted app" from the bottom right of the screen, future refunds should again update the corresponding Klarna order, including orders older than 60 days. For already processed refunds, the order can be updated through the Klarna Merchant Portal: https://eu.portal.klarna.com or https://us.portal.klarna.com

4. Editing Klarna orders in Shopify admin not yet supported

The Klarna Payments for Shopify integration does not yet support Shopify’s edit orders functionality: https://help.shopify.com/en/manual/orders/edit-orders These updates will not be sent from to Klarna. These updates must be manually edited in the Klarna order via the Klarna Merchant Portal.