During the checkout billing step, Klarna payment options are dynamically displayed based on the customer’s cart details and the payment method categories available for the current Klarna session.

When the customer selects a payment method, a widget displaying additional information about the Klarna product will appear.

Klarna payment methods may not be displayed under the following conditions:

1. Payment Categories Not Returned: Klarna is not displayed if payment categories are not returned in the session response.
2. Session Linking Issue: Payment method content is not displayed if we have payment methods in the session, but no session is linked to the basket.
3. Authorization Denial: Payment method category is hidden or grayed out if show_form is returned as false in the Klarna response on an authorization request and the payment method is denied.
4. Session Creation Failure: Overall, if Klarna is unavailable and a session is not created, payment categories will not be displayed.

We've implemented a site preference, kpRejectedMethodDisplay, allowing merchants to choose how to handle authorization rejections (refer to section 2.3.5 Refusal of Klarna Payments on Payment Method – Authorization). The available options are:

• No action: No specific handling for authorization rejections.
• Hide: Hide the payment method upon authorization rejection.
• Gray out: Gray out the payment method upon authorization rejection.

The cartridge implementation follows best practices for integrating Klarna payment methods, offering the inclusion of Extra Merchant Data (EMD) to optimize acceptance rates. EMD can include customer information and Buy Online, Pickup in Store (BOPIS) details when the custom site preference attachments is enabled. Merchants should review and validate EMD data based on their data privacy requirements prior to going live.

When a customer selects a Klarna payment method and clicks "Continue to Place Order," their personally identifiable information (PII) is sent. This information is essential for assessing and verifying the customer's data to display available payment method options.

Steps:

1. Customer Action: The customer selects a Klarna payment method and clicks "Continue to Place Order."
2. Authorization Initiation: Authorization is initiated, sending PII to Klarna for verification.
3. Authorization Outcome:
   - Success: The customer is taken to the summary page.
4. - Additional Information: Depending on the payment method and market, additional information may be requested before completing authorization.
5. - Failure: If authorization is not successful (approved = false), the customer remains on the billing page, no changes to payment options display.

Special Case: Pay Now

For the Pay Now payment category, an additional "finalize" call is required when the customer clicks the "Place Order" button on the review page. This ensures that funds are transferred only when the customer decides to place the order. A cookie called selectedKlarnaPaymentCategory is set in the customer's browser to initialize the finalize call to Klarna.

The Klarna order is placed just before the SFCC order is created:

• Approved: Successful payment authorizations (Klarna Payments authorization status: APPROVED) result in the creation of both Klarna and SFCC orders with a "Paid" order payment status and "Ready for Export" export status.
• Rejected or Pending: Refused and pending Klarna Payment orders (statuses REJECTED and PENDING) result in a "Not Paid" order payment status and "Not Exported" export status.
• VCN Settlement Errors: Klarna orders are canceled, and SFCC orders are set to a "Not Exported" export status.

If a customer authorizes a Klarna payment and then returns to the billing page to select a different non-Klarna payment method, an automatic cancelAuthorization call is triggered. This releases the authorized funds and frees up the available purchase amount. Merchants can utilize this function for specific use cases.

server.get('SaveAuth', function (req, res) {
	var KlarnaSessionManager = require('*/cartridge/scripts/common/klarnaSessionManager');
	// var processor = require('*/cartridge/scripts/payments/processor');

	var token = req.httpHeaders['x-auth'];
	var finalizeRequired = req.httpHeaders['finalize-required'];

	//Cancel any previous authorizations
	//processor.cancelAuthorization();

Merchants should thoroughly test the checkout flow, including scenarios such as:

• Klarna session flow
• Payment method switching
• Order amount updates
• Checkout with external payment methods

Upon selecting Klarna as the payment method on the billing step of checkout and based on the customer information provided, Klarna Payments can be refused as a payment method. If the payment method is rejected with show_form=false and approved=false (i.e., hard reject), the merchant can choose how the payment option is displayed on the Billing page using the Business Manager (BM) preference Hide Payment Methods on Deny (kpRejectedMethodDisplay):

• No: Leave the payment visible to the customers.
• Hide: The payment option will be hidden from the customer.
• Gray Out: The payment option will be grayed out and not clickable.

The customer is presented with an appropriate message in the Klarna widget when the customer attempts to choose Klarna in the billing step.

If the Klarna API is unavailable or the site/storefront is inapplicable, Klarna will not be presented as a payment option on the billing page. It is recommended that a Klarna session not be created when a customer selects a non-Klarna market or merchant store. This also applies to cases where merchants have multi-currency storefronts with a basket currency not supported by Klarna.

When a Klarna order is created but flagged for additional review, the Commerce Cloud order remains in the Created status with a Fraud Status of PENDING. This order is marked with EXPORT_STATUS_NOTEXPORTED, confirmation status NOTCONFIRMED, and NOTPAID.

For orders with a Fraud Status of PENDING, updates are sent to the pre-configured notification_url on the merchant's Commerce Cloud site once the review is complete. The updated Fraud Status, such as FRAUD_RISK_ACCEPTED, is displayed in Business Manager (BM). Push notifications are sent repeatedly (up to 24 hours, every 10 minutes) until the POST request is acknowledged with a 200 response.

Klarna sends one of the following event types in the notification to SFCC to update the risk status:

• FRAUD_RISK_ACCEPTED
• FRAUD_RISK_REJECTED
• FRAUD_RISK_STOPPED

Notifications are generally received within 4-24 hours. The order’s payment transaction is updated accordingly (see kpFraudStatus). This status can be viewed in BM on the order details Payment tab.

FRAUD_RISK_ACCEPTED

• Order Status: Changes to OPEN.
• Confirmation Status: Changes to CONFIRMATION_STATUS_CONFIRMED.
• Export Status: Changes to EXPORT_STATUS_READY.
• Auto-Capture Orders: The payment status will be set to PAYMENT_STATUS_PAID, and the full order amount will be captured.

FRAUD_RISK_REJECTED or FRAUD_RISK_STOPPED

• Order Status: Marked as failed (FAIL) in SFCC.

This feature is disabled by default. However, if standard order management is not suitable for your Klarna integration, you can utilize Klarna’s Merchant Card Service-based virtual card solution. The virtual card is issued against a Klarna order to capture the authorized order amount using standard card rails.

When a customer places an order, it is first booked in SFCC. Once Klarna accepts the order, the Klarna cartridge integration creates a virtual card-based settlement using the Merchant Card Services (MCSv3) API.

After the settlement is created (virtual card returned), the encrypted card details are saved in SFCC. These details can later be used by the merchant's OMS platform or custom PSP integration to authorize the virtual card until the Klarna order is valid. On successful order fulfillment, the funds on the virtual card may be captured. (For delays in capture or special use cases, please speak with the Klarna Key Account Manager in advance). While Klarna is the original payment method, the order amount will be settled with the merchant using the issued virtual credit card instead of a direct bank account transfer.

Please review the procedures with the Klarna team for details of the settlement process using virtual cards. Refer to the code in scripts/payments/processor.js and update accordingly to the integrated cards processor.

Credit card authorization call:

/**
* Call Credit Card Authorization Hook (for VCN settlement)
* @param {dw.order.order}.order DW Order
* @returns {processorResult} authorization result
*/

function callCreditCardAuthorizationHook(order) {
	var processorResult = null;
	var paymentInstrument = order getPaymentInstruments(PAYMENT_METHOD)[0];
	var paymentProcessor = PaymentMgr

If enabled and fully configured, a virtual card settlement request is made successfully. For orders placed with the VCN settlement option, the related custom attributes are shown below:

If required, the additional virtual card details can be assigned to this group in Administration > Site Development > System Object Types > select “Order”. In the Attribute Grouping tab, select Klarna_Payments and click on “edit”. Assign the new attributes and save the data.

Work with your Klarna Account Manager and Delivery contact in advance to select the appropriate virtual card product based on your business requirements and use cases. You can find information here about other supported use cases.

Depending on their credentials configuration, merchants should follow these steps to utilize the virtual card integration option:

1. Enable VCN option in Site Preferences as shown below.

1. Enter the VCN Public Key ID. Unique UUIDv4 value, which should be different for playground testing and Production (live site).

1. Generate a 4096-bit RSA key pair (Refer to Overview of Merchant Card Service).
2. Update the VCN settlement retry setting. By default, this is disabled. However, if enabled and in cases when a VCN creation error is returned, the application will retry the settlement request once again with order_id as the idempotency key.
3. Send the generated unique key_id + public key combination in JWK format to Klarna before testing and going live. It will be used to encrypt the AES key, which encrypts the PCI data on Klarna's side when the settlement request is made. After confirmation from Klarna that the key has been successfully added to your merchant profile, you will be able to use the virtual card-based settlement option for Klarna payment methods.

1. Go to Merchant Tools > Custom Objects > Manage Custom Objects and select KlarnaActivation.
2. Search and locate the custom object entry.
3. Enable the VCN option.
4. Enter the VCN Public Key ID, a unique UUIDv4 value, which should be different for Playground (testing) and Production (live site) environments.
5. Update the VCN settlement retry setting. By default, this is disabled. If enabled, in cases when a VCN creation error is returned, the application will retry the settlement request once again with order_id as the idempotency key. 

1. Generate a 4096-bit RSA key pair (Refer to Overview of Merchant Card Service).
2. Send the generated unique key_id + public key combination in JWK format to Klarna before testing and going live. It will be used to encrypt the AES key, which encrypts the PCI data on Klarna's side when the settlement request is made. After confirmation from Klarna that the key has been successfully added to your merchant profile, you will be able to use the virtual card-based settlement option for Klarna payment methods.

To decrypt the virtual card details stored at the order level and authorize the credit card processor, you can use the following code snippet. This script utilizes the Salesforce Commerce Cloud (SFCC) APIs and classes for cryptographic operations.

var OrderMgr = require( 'dw/order/OrderMgr' );
 var Cipher = require( 'dw/crypto/Cipher' );
 var Encoding = require( 'dw/crypto/Encoding' );
 var Site = require( 'dw/system/Site' ); 

var Order = OrderMgr.getOrder( "order_id" );
 var VCNPrivateKey = Site.getCurrent().getCustomPreferenceValue( 'vcnPrivateKey' );
 var cipher = new Cipher(); 

var keyEncryptedBase64 = Order.custom.kpVCNAESKey;

Steps:

1. Retrieve the Order: Use OrderMgr.getOrder("order_id") to fetch the order by its ID.

2. Store the VCN Private Key in SFCC: Create a custom attribute to store the private key.

3. Create Site Preference for Single Site Credentials: Go to Administration > System Object Types; select Site Preferences; click on Attribute Definitions; click New to create a custom attribute; define the attribute with ID vcnPrivateKey, Display Name VCN Private Key, Description SSL private key used only to decode Virtual Card information (used with kpVCNEnabled), Type Text, and set Mandatory to false; click Apply to save; click on Attribute Grouping; select the Klarna_KP group; add the new attribute vcnPrivateKey and save; navigate to Merchant Tools > Site Preferences > Custom Site Preference Groups > Klarna Payments and update the vcnPrivateKey value.

4. Create Custom Object Attribute for Multiple Klarna Credentials per Site: In Business Manager, go to Administration > Site Development > Custom Object Types; edit the custom object type named KlarnaActivation; navigate to the Attributes tab; click New to create a new attribute with Attribute ID vcnPrivateKey, Display Name VCN Private Key, Description SSL private key used only to decode Virtual Card information (used with kpVCNEnabled), Value Type Text, and ensure Mandatory is unchecked; navigate to the Attribute Groups tab; edit the vcn attributes group; add the attribute vcnPrivateKey to the group; go to Merchant Tools > Custom Objects > Manage Custom Objects; select the KlarnaActivation ObjectType and search; enter the vcnPrivateKey for each entry.

5. Retrieve the VCN Private Key: From Site Preferences (single credentials), use Site.getCurrent().getCustomPreferenceValue('vcnPrivateKey'); from Custom Object, review KlarnaHelper.getVCNKeyId() and create a similar function to retrieve the private key using its ID vcnPrivateKey.

6. Decrypt the AES Key: Convert the encrypted AES key from Base64 to bytes using Encoding.fromBase64; decrypt the AES key using cipher.decryptBytes with the RSA algorithm.

7. Decrypt the Card Data: Convert the encrypted card data from Base64 to bytes using Encoding.fromBase64; decrypt the card data using cipher.decryptBytes with the AES algorithm.

8. Parse and Extract Card Details: Decode the decrypted card data from URL encoding to UTF-8 format; parse the JSON string to obtain the card details object; extract the card PAN, CVV, and expiry date.

9. Authorize the Credit Card Processor: Use the decrypted card details to proceed with the credit card authorization process.

Auto-capture is enabled via a site preference kpAutoCapture located in the Klarna_Payments preference group. By default, auto-capture is disabled. When enabled, the system attempts to capture the full payment amount automatically.

• The SFCC order’s payment transaction is marked as Paid.
• The transaction status is viewable in the Business Manager.
• The order status in Klarna’s Merchant Portal is updated to Captured.

• An error is logged in the custom error log.
• The issue must be reviewed with the Klarna delivery team before testing and going live.

The Klarna Payments widget can be styled to align with the marketing and branding needs of the merchant's store. Various graphic elements of the widget can be customized through site preferences.

The payment method name “Klarna Payments” can be customized in the Business Manager.

Steps to Customize

1. Navigate to Merchant Tools > Ordering > Payment Methods in Business Manager.
2. Select the Klarna payment method.
3. Choose the desired language from the drop-down menu.

The customized payment method name will be displayed in:

• The mini summary and confirmation screens
• Confirmation emails
• The My Account Order Details section