Klarna Instant Shopping - Implementation guide¶

Target Audience: Developers

Release version: 4.4.3

Introduction¶

This document describes how to integrate Klarna Instant Shopping for subscriptions. In short Klarna Instant Shopping (KIS) is a widget supplied by Klarna that presents a different frontend solution for Klarna Payments purchases.

Requirements and limitations¶

Make sure to read and adhere to Klarnas prerequisites.
You need to create a Klarna Instant Shopping button key as described here. Make sure that you create this button key with the same Klarna API credentials that you are using in Payway.

Create customer token url¶

Environment	Url
Stage	https://payway-api.stage.adeprimo.se/api/payment_provider_callback_api/klarna_instant_shopping_token_callback/
Production	https://backend.worldoftulo.com/api/payment_provider_callback_api/klarna_instant_shopping_token_callback/

Overview¶

There are three distinct Payway (PW) integration steps that you need on your site to be able to leverage KIS in addition to the actual KIS widget.

When loading the KIS widget you need to generate a unique key to identify the specific purchase instance and supply it in the loading call as reference on the order_line.
You need to react to the KIS widgets buy_button_clicked-event and initialize a KIS purchase session in PW.
You need to poll PW for purchase status, and react to it, when the KIS widget has redirected the end user to the confirmation page.

Payment Process¶

Overview

(1) When the user clicks the buy button the KIS widget will start processing the purchase and the buy_button_clicked-event will fire. The site reacts to this event by making a XHR-request to its own backend supplying information about the purchase, including the generated unique identifier (purchase_id) for this purchase.

(2) The site backend calls the Payway API to create a KIS Purchase identified by the generated purchase_id.

(3) When the purchase process is completed the KIS widget will redirect the browser to the confirmation page configured when loading the widget. The site will check the purchase status with Payway API when loading the confirmation page.

(4) If the purchase status was "pending" when loading the confirmation page the browser will need to XHR-poll until the purchase status changed to either "approved" or "declined" to know when the purchase process has been completed.

When displaying the KIS widget please refer to Klarnas Documentation for further details.

An important detail here is the fact that you need to create a unique identifier for the purchase, see purchase_id below. This identifier will be used as a mean to track the purchase process between KIS and PW.

An example on how this could look:

<script>
        var purchase_id = "<insert generated unique value here>";

        window.klarnaAsyncCallback = function () {
            window.Klarna.InstantShopping.load({
                setup: {
                    instance_id: "signup-widget",
                    key: "4b6d1xxx-10xx-41be-axx5-c2617dxxxxb5",
                    environment: "playground"
                },
                tokenization: {
                    description: "Legal text, describing the conditions of this subscription. E.g. Read first two months for free, then the monthly cost until further notice."
                },
                styling: {
                    theme: {
                        type: "paywall"
                    }
                },
                purchase_country: "SE",
                purchase_currency: "SEK",
                locale: "sv-se",
                merchant_urls: {
                    confirmation: "https://localhost:44321/confirmation?purchase_id=" + purchase_id,
                    terms: "http://localhost/terms"
                },
                order_lines: [{
                    image_url: "http://localhost/image.png",
                    type: "digital",
                    reference: purchase_id,
                    name: "Subscription",
                    quantity: 1,
                    unit_price: 10000,
                    tax_rate: 0,
                    total_amount: 10000,
                    total_discount_amount: 0,
                    total_tax_amount: 0,
                }]
            }, function (response) {
                console.log('Klarna.InstantShopping.load callback with data:' + JSON.stringify(response));
            });
</script>

Reacting to buy_button_clicked event¶

When the buy button is clicked you need to establish a KIS purchase in PW. The purchase will be identified by the purchase_id that you used when loading the KIS widget. This call must be made as a XHR-request to your application backend. Your backend can then call the PW API:s. Please see details about the endpoint used here.

The buy_button_clicked-event can be emitted more than once, depending on if the end user has a Klarna Cookie or not. Make sure to only react to it if the callbackData.session_id is not null.

Please note that the example below is just an example, what values you get from where is an implementation detail that we leave up to you.

window.Klarna.InstantShopping.on('buy_button_clicked', function (callbackData) {
    console.log('Buy Button Clicked:', callbackData)
    if (callbackData.session_id == null) {
        console.log('session_id is null, skipping')
        return;
    }

    var body = JSON.stringify({
        purchase_id: purchase_id,
        account_id: '5e71de4395cfebf9eff4f9aa',
        code: 'mm_plus_premium',
        period_type: 'recurring',
        period_id: '5d8b72a195cfebba4759fd5b',
        client_ip: '127.0.0.1',
        client_user_agent: 'edge...',
        client_language: 'sv',
        traffic_source: 'youtube',
        merchant_reference: 'merchant reference here'
    });

    const url = "https://localhost:44321/init";
    fetch(url, {
        method: "POST",
        body: body,
        headers: {
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        }
    }).then(
        response => response.text()
    ).then(
        html => console.log(html)
    );
}, {
    setup: { instance_id: 'signup-widget' }
});

Confirmation Page¶

When the purchase process is completed the KIS widget will redirect the browser to the confirmation page configured in the KIS widget load-call. When this happens there is no guarantee that the purchase process has actually finished. We recommend that when you display the confirmation page you initially call the PW API /purchase_status and if the status is "pending" you then continue polling the endpoint until you get a status of either "approved" or "declined" and react accordingly.

FAQ¶

How do I use a free-trial campaign that continues on normal price after the campaign period?¶

In order to accomplish this you need to have a campaign in Payway that:

is set up to continue with normal price after the campaign period ends
has a period with price 0 (zero) that is paid with Klarna Payments.

When initializing your KIS purchase you use the product code and period id period id of the previously mentioned campaign and period.