This guide provides detailed instructions to install the cartridge on Salesforce Commerce Cloud (SFCC) SiteGenesis stores.
The Klarna Payments LINK Cartridge contains two cartridges required for full functionality. Controller and SiteGenesis support are separated into two distinct cartridges, facilitating the installation and use of either model:
int_klarna_payments
: Implements the core storefront functionality.int_klarna_payments_controllers
: Implements the storefront functionality with SG code.1. Import the int_klarna_payments
cartridge into the SCC Studio Workspace:
int_klarna_payments
cartridge.2. Import the int_klarna_payments_controllers
cartridge into the SCC Studio Workspace:
int_klarna_payments_controllers
cartridge.3. Prepend the Klarna cartridges to the effective site cartridge path:
int_klarna_payments_controllers:int_klarna_payments
to the Cartridges field.site-template.zip
installation package.site-template.zip
.Review the default service.xml
file in the site-template.zip
and update the configuration for Playground and Production accordingly before importing.
As of version 24.4.0, the cartridge configuration process has changed. If you are using a version older than 24.4.0, please refer to the Deprecated Features section of the Changelog for detailed information on the configuration changes.
client_id
to activate OSM and KEC.Controller | Start Node | Remarks |
---|---|---|
Checkout.js | Begin | Extended to call Klarna session manager |
CheckoutServices.js | Get, SubmitPayment, PlaceOrder | Klarna payment method/category and totals are being stored |
CheckoutShippingServices.js | SubmitShipping, ToggleMultiShipping | Calling the Klarna session manager |
Order.js | Confirm | Extending Klarna order data to view data |
The templates have been updated to support On-site Messaging and Address Forms for Klarna. These templates are intended for reference, but you can customize them to suit your specific needs. Please ensure that the final review and sign-off align with your project requirements and contractual agreements.
This one-time clean-up job is applicable only to merchants integrated with Klarna Payments cartridge version earlier than 19.1.6, utilizing (or previously used) virtual card-based settlement (VCN) and stored decrypted card details within Business Manager.
The job iterates over orders with status Exported
and the attribute custom.kpIsVCN=true
to remove sensitive details saved in fields kpVCNPAN
, kpVCNCSC
, kpVCNExpirationMonth
, and kpVCNExpirationYear
from previous releases. No parameters are passed to the script.
Upon successful run, the job logs the result of processed orders in the custom debug log located in webdav/Sites/Logs
. You will receive a message indicating the processed orders count for each storefront or a message indicating that there are no orders needing update.
In case of an error, the cause of the failure (message and stack trace) will be logged in the standard error log.
Ensure that you have access to the SFCC Business Manager and that the jobs.xml
configuration file is prepared and accessible.
Log into the SFCC Business Manager, and go to Administration > Operations > Import & Export.
Click on the Import button, and browse for the jobs.xml
file and select it for import.
The default scope included in the XML file is for RefArch. If you have multiple sites using this functionality, you need to configure each site as a separate flow within this file.
After the job import is complete, navigate to the flow section within the job, and scroll down to the bottom of the current flow.
Click on the Add a sequential flow button. This action will create a new flow under the current job configuration.
In the newly added flow, click on the Configure a step button. When the flyout appears, search for the term script, and select the ExecuteScriptModule
from the list.
Enter the step details:
OrderCleanUpJob.js
file. The default path is int_klarna_payments/cartridge/scripts/job/OrderCleanUpJob.js
, but this can vary depending on where the script is placed.Click on the Assign button to save the step configuration.
Repeat steps 1-5 for each site/storefront that you have using Klarna VCN and need additional configuration. This ensures that the clean-up job runs for all relevant sites and removes sensitive data as required.
The RecurringOrders
job is designed to process subscription entries for all customers. The job performs the following functions:
nextChargeDate
or nextRetryDate
matches the current date.Configuration
By default, the job is set to run on the RefArch site, as specified in the jobs.xml
file. This setting can be modified either in the jobs.xml
file or through the storefront configuration.
The job consists of a single step, createOrder
, with the following configuration:
int_klarna_payments/cartridge/scripts/job/RecurringOrdersJob.js
execute
The job operates at site level.
Ensure your configuration matches these details to maintain the proper functionality of the RecurringOrders job.
Integration may vary based on the storefront version. Site Genesis version 105.0.0 is used as a reference to demonstrate Klarna integration.
The following template changes should be made regardless of whether a controller or a pipeline integration approach are being used:
default/checkout/summary/summary.isml
default/checkout/billing/billing.isml
default/checkout/billing/paymentmethods.isml
default/checkout/shipping/minishipments.isml
default/components/header/header.isml
default/components/footer/footer.isml
default/components/footer/footer_UI.isml
default/product/producttopcontentPS.isml
default/product/productcontent.isml
default/product/productcontent.isml
default/checkout/cart/cart.isml
default/mail/orderconfirmation.isml
default/components/order/ordrdetailsemail.isml
default/checkout/cart/minicart.isml
js/pages/cart.js 79
default/checkout/shipping/singleshipping.isml 82
scripts/cart/ValidateCartForCheckout.js 83
scripts/util/Resource.ds 84
js/pages/account.js 84
default/account/orders.isml 87
default/checkout/components/minicheckout_address.isml 87
js/minicart.js
default/checkout/summary/summary.isml
Add the following code before the closing </isdecorate>
tag at the end of the file:
Update the condition on line 232, for the finalize script include:
Ensure the updated condition for the finalize script is applied correctly to handle both the finalize and express checkout scenarios.
default/checkout/billing/billing.isml
Add the following code before the closing </isdecorate>
tag at the end of the file:
default/checkout/billing/paymentmethods.isml
Add the following code after <div class="form-row label-inline
close to line 18 as shown below:
Add the following code after the </isloop> tag, close to line 28:
Add the following code before the closing </fieldset>
tag, close to line 150:
default/checkout/shipping/minishipments.isml
To integrate Klarna Payments into the minishipments.isml
file, follow these steps:
Add the following code at the beginning of the minishipments.isml
file. This step includes the necessary Klarna Payments modules for the mini shipments template.
After the line containing <isminicheckout_address p_address="${shipment.shippingAddress}"/>
, add the code below. This step adds the Klarna Payment Address Helper, which manages the shipment and shipping address.
default/components/header/header.isml
Add the following code before the <script src="${URLUtils.staticURL('/js/app.js')}"></script>
script tag:
default/components/footer/footer.isml
Add the following code right after the </footer>
end tag and before the <iscontentasset aid="footer-copy"/>
tag:
This includes the Klarna OSM footer and KEB form in the footer template.
default/components/footer/footer_UI.isml
Add the following code right under the pricing template include:
default/product/producttopcontentPS.isml
Add the following code right under the pricing template include:
Add the following JavaScript code on line 24 within the <isscript> element:
Add the following code on line 256, right after the "Add to Cart" button:
default/product/productcontent.isml
Add the following code in the variation update callback on line 35:
Add the following code in the variation update callback on line 37:
default/product/productcontent.isml
Add the following code on line 5:
Add the following code on line 823, right after the <isordertotals> tag:
Add the following code on lines 33 and 864, right after the <isif condition="${enableCheckout}">
tag:
Add the following code on line 182:
after the deliveryoptions
include:
Add the following code on line 65, inside the div with class error-form
:
Add the following code on line 862, at the end of the div with class cart-footer
:
Add the following code on line 34, before the checkout button:
Add the following code on line 879, in the enabledCheckout
case before the checkout button:
This includes the Klarna Express Checkout component for the enabled checkout case.
default/checkout/cart/cart.isml
Add the following code at the end of the file:
default/mail/orderconfirmation.isml
Add the following code before the closing </table>
tag:
This includes the Klarna confirmation email asset in the order confirmation email.
default/components/order/ordrdetailsemail.isml
Add the following code before the closing </isif>
tag on line 51:
This conditionally includes the Klarna order reference in the order details email if the payment method is Klarna.
default/checkout/cart/minicart.isml
Add the following code before the <a class="mini-cart-link-checkout"...
tag on line 74:
This sets the Klarna OSM variable, checks if the mini cart express button is enabled, and includes the necessary Klarna templates and scripts.
Add the following code before the <a class="mini-cart-link-checkout"... tag on line 81:
This conditionally includes the Klarna Express Checkout button in the mini cart based on specific conditions.
js/pages/cart.js
Add the following code after line 6:
This imports the util module for use in the cart script.
Add the following code at the end of the initializeEvents()
function:
This handles changes to the subscription checkbox.
Add the following code on line 75:
This handles changes to the subscription period and frequency dropdowns.
default/checkout/shipping/singleshipping.isml
Add the following code after line 98, after the shipping method list:
This includes the subscription details template within a fieldset after the shipping method list.
Add the following code on line 145, before the closing </isdecorate>
tag:
scripts/cart/ValidateCartForCheckout.js
Add the following code block in the validate
function before the DONE
section on line 115:
This code block performs validation on the cart products for subscriptions and handles any subscription-related errors.
scripts/util/Resource.ds
Add the following code block before the validation messages section:
This includes resource messages for canceling subscriptions and a global cancel action.
js/pages/account.js
Add the following code block after the initializePaymentForm()
function:
This function initializes events for handling subscription cancellation.
Add the following code in the initializeEvents()
function to call the initSubscriptionEvents()
function:
This ensures that the subscription events are initialized when the account page is loaded.
default/account/orders.isml
Add the following code within the order-history-header
div:
This conditionally displays the subscription ID if the kpCustomerToken custom attribute is present on the order.
default/checkout/components/minicheckout_address.isml
Add the following code on line 16:
js/minicart.js
Add the following code on line 38 in the mouseenter
event:
This code initializes Klarna Express Checkout in the mini cart when the mouse enters the mini cart area.
Add the following code on line 60 in the show minicart event:
This code initializes Klarna Express Checkout in the mini cart when the mini cart is shown.
default/account/login/oauthlogininclude.isml
Add following code on line 15:
If using a controller based SiteGenesis integration, additionally follow the instructions in this chapter.
COBilling.js
In the returnToForm()
method, add the following code block after the pageMeta.update()
function:
This code attempts to create or update a Klarna session and logs an error if it fails.
In the resetPaymentForms()
method, add the command to remove Klarna payment instruments for the three conditions:
This ensures that any Klarna payment instruments are removed when resetting the payment forms.
In the handlePaymentSelection(cart)
method, go to line 441 and add the following code block:
This cancels any Klarna authorizations if the selected payment method is not Klarna.
COSummary.js
In the submit()
method, add the following code block before the showConfirmation(placeOrderResult.Order)
function:
This code attempts to handle the Klarna redirect and logs an error if it fails.
OrderModel.js
In the placeOrder
method, add the following code block before the var placeOrderStatus = OrderMgr.placeOrder(order)
; line:
This code handles orders with a pending Klarna fraud status by calling the PendingOrder
method and logs an error if it fails.
In the placeOrder
method, add the following code at the end:
This code updates the customer subscription data if a customer token is present in the session.
This code checks if the product is a subscription product and updates the product line item accordingly.
In the addProductItem
function, add the following code block on line 220:
This code checks if the product is a subscription product and updates the product line item accordingly.
Cart.js
Add the following code before the module exports section:
This function handles AJAX requests to update the subscription status of a product in the cart.
Add the following code before the module exports section:
This function handles AJAX requests to update subscription details in the cart.
Add the following code at the end of the exposed methods section:
This exposes the newly added methods to handle subscription updates.
COShipping.js
Add the following code after the cart calculation on line 100:
Order.js
Add the following subscriptions function at the end of the controller:
This function retrieves the customer's subscriptions from their profile and renders the subscription history page.
Add the following module export for the subscriptions
function:
This ensures that the subscriptions
function is accessible and secured.
COCustomer.js
Add the following code on line 38, after the removeAllPayments()
call:
This code validates the subscription products in the cart and updates the cart subscription details. If there's an error, it redirects to the cart page.
Update app.getView
on line 68 by adding following code:
The code passes a scope parameter to the view.
COPlaceOrder.js
Update the start()
function with a parameter in attributes and pass it to the cart model:
This modification ensures that the start()
function accepts a parameter and uses it to get the cart.
Login.js
Add klarnaSignIn
function after Logout()
function:
Export function at the end:
Account.js
Add following code on line 390 to validate if the user already exists as externally authenticated Klarna user:
All requests to Klarna are performed through Klarna’s REST API and are encrypted using SHA-256 with the shared secret provided by Klarna. To ensure security, only HTTPS is allowed for these communications. JSON is the format used for all requests and responses, facilitating consistent and structured data exchange.
For detailed information, including the resource structure for requests and responses, please refer to Klarna Payments API.