Klarna Docs - Installing Klarna Payments as an alternative payment method on Shopify (HPSDK)

Installing Klarna Payments as an alternative payment method on Shopify (HPSDK)

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 at the Merchant Portal button in the top navigation of docs.klarna.com

Start the Klarna Payments Shopify setup wizard: 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 unlisted Klarna Payments app:

This will take you to your Shopify store admin page or login page if you are not logged in already. Then you’ll receive a page requesting your consent to install the unlisted Klarna Payments app. Click Install unlisted app. (This app is unlisted as Shopify generally does not allow payments apps to be listed on the Shopify app store.)

You’re then redirected back to the setup wizard to continue the integration. Under “Authenticate Klarna API Credentials”, enter your production Klarna API credentials that you generated from the Settings option in the Klarna Merchant Portal. Do not use Test mode if your store is live, as Klarna will not pay out for test orders. Do not enter an email address.

Your API credentials will be verified against the appropriate Klarna API endpoint for your store's base currency, and authentication results are displayed. Note: Klarna API credentials work for either test or production environments, but the same credentials do not work for both environments. The currency for your store must match your Klarna contract; USD or CAD require Klarna North American credentials; not European credentials.

  1. Click the available link, OR from your Shopify admin page, go to Settings in the bottom left corner.
  2. Go to “Payment providers”, and scroll down to “Alternative payment methods”.
  3. Select your contracted Klarna payment alternative payment method(s) and enter your Klarna API 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 alternative payment method(s) MUST exactly match (including whitespace and case) the credentials entered in the 2nd tab of the setup wizard (include Test Mode setting) 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. (If desired, place an order from this page, but remember to cancel it.)

If the Klarna API credentials don’t match in both places, the Klarna page shows an error message: “Oops error - If you are a Shopify administrator for this store, please verify the configuration of the Klarna Payments app and contact Klarna to verify credentials.” If you get this error, verify your API credentials in both places: 1) the Klarna Payments app (under Apps) and 2) Klarna Alternative Payment Method(s) (under Settings->Payments->Alternative payment methods). We recommend to copy/paste API API credentials to eliminate typos but make sure to not copy any extra whitespace.

The alternative payment methods are configured as available based on your store’s address (in your Shopify admin, under Settings->Address). If you would like to activate a payment method for a language that isn’t available for the country where your store is located, please work with Klarna merchant support to schedule a time where the payment method can be temporarily enabled for your store’s country. If you’d like to use English payment methods but your store is located in a country where English payment methods aren’t publicly available, you can install the private payment method(s) (and then activate them after install):

Private English payment method namePayment method installation URL
Pay now. Klarnahttps://www.shopify.com/login?redirect=%2Fadmin%2Fauthorize_gateway%2F1052409
Buy now, pay later with Klarna.https://www.shopify.com/login?redirect=%2Fadmin%2Fauthorize_gateway%2F1054583
Pay over time with Klarna.https://www.shopify.com/login?redirect=%2Fadmin%2Fauthorize_gateway%2F1054581

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: On-site messaging app for Shopify

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

To require email in Shopify Checkout, under Shopify admin →  Settings →  Checkout →  Customer contact, choose the “Customers can only check out using email”. 

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 real-time at public demo store: https://klarnastore.myshopify.com

Klarna Merchant Portal

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. Please verify your Klarna API credentials (username & password) are correctly entered in both the Klarna Payments app configuration and in your Shopify store (under Alternative Payment Methods).  The Klarna API credentials entered in your Shopify admin alternative payment method(s) MUST exactly match (including whitespace and upper vs lower case) the credentials entered in the 2nd tab of the setup wizard (include Test Mode setting).  We recommend copying & pasting the credentials rather than typing them directly.  (error code: 401, error message: UNAUTHORIZED or Oops error - If you are a Shopify administrator for this store)
  2. If you’ve regenerated Klarna API 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 payment methods → all active Klarna alternative payment methods AND Shopify admin → Apps → Klarna Payments (which redirects to the setup wizard)
  3. 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 support EU stores selling in USD, but can support EU stores selling in EUR.(error code: 400, error message: Bad value: purchase_currency)
  4. If the Klarna Payments page is still not loading successfully, please contact Klarna Merchant Support.

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 and have required data to place the order in Klarna, the order line item data is also needed.  Shopify generally restricts payment processing apps to be unlisted apps, so the Klarna Payments app is not publicly available in the Shopify app store.  This Klarna Payments app for Shopify is required and installed during the setup process:

www.klarnapayments.com/install

Shopify does not yet support alternative payment methods, like Klarna, to integrate into Shopify's POS sales channel. Customers in store can still easily still pay with Klarna using Shopify Draft Orders though. To do so, follow 3 easy steps:

  1. Create a Shopify draft order for a customer (with optional customer details prepopulated) with the desired products. (Do not check "Payment due later" or set the order as "Paid").
  2. Email the invoice to the customer from the Shopify draft order admin page using the "Send invoice" button.
  3. The customer then can pay for the draft order via your Shopify store's Online Store sales channel using your store's Shopify web checkout and choose Klarna (or any payment option available in checkout).

Klarna’s order management will work for Shopify draft orders paid with Klarna 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 other Klarna online orders).

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

Note: Klarna cannot currently accept Shopify Draft Orders marked as “Payment pending”, which is set when a draft order is checked as "Payment due later". Pending payment draft orders create a Shopify order, instead of a Draft order, and then adding a payment method would use the Order Edit flow, which is not currently able to be supported, per Known Issue #7: “Editing Klarna orders in Shopify admin not yet supported” . This functionality will hopefully be supported in the future with the upcoming Shopify new Payments architecture. Note: only draft orders marked as "Payment pending" update Shopify inventory.

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

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.

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 (only recommended for test stores).  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 Klarna’s test environment.  

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

This integration requires each Shopify store to have a unique set of Klarna API credentials.  These credentials cannot be shared across stores.  If Klarna API production credentials were installed using a test store, a Klarna person will need to delete that configuration before those same credentials can be used for a live store.  Klarna API test credentials are recommended for test stores.