This product, Klarna Checkout (v2) is deprecated. Go to the current version

Embed the Checkout

This tutorial will guide you in how to render the Klarna Checkout HTML snippet in your checkout page. When you create an order in Klarna’s system it will have the status checkout_incomplete.

Use case

A consumer has proceeded to the checkout and you want to display Klarna Checkout to the consumer.

Prerequisites

When using Klarna’s APIs you must provide the merchant ID and the shared secret that you received when you applied for API credentials.
You have prepared your site for Klarna Checkout .

1. Add the cart items

Add the cart items according to the API reference. The example code below is populated with example data for the test order.

Note: Find out more about the different fields in the cart items list in the API reference .

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
final Map<String, Object> cart = new HashMap<String, Object>() {
    {
        put("items", new ArrayList<HashMap<String, Object>>() {
            {
                add(new HashMap<String, Object>() {
                    {
                        put("quantity", 2);
                        put("reference", "123456789");
                        put("name", "Klarna t-shirt");
                        put("unit_price", 12300);
                        put("discount_rate", 1000);
                        put("tax_rate", 2500);
                    }
                });
                add(new HashMap<String, Object>() {
                    {
                        put("quantity", 1);
                        put("type", "shipping_fee");
                        put("reference", "SHIPPING");
                        put("name", "Shipping Fee");
                        put("unit_price", 4900);
                        put("tax_rate", 2500);
                    }
                });
            }
        });
    }
};
Map<String, Object> data = new HashMap<String, Object>();
data.put("cart", cart);

Java

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
$create['cart']['items'] = array();

$cart = array(
    array(
        'reference' => '123456789',
        'name' => 'Klarna t-shirt',
        'quantity' => 2,
        'unit_price' => 12300,
        'discount_rate' => 1000,
        'tax_rate' => 2500
    ),
    array(
        'type' => 'shipping_fee',
        'reference' => 'SHIPPING',
        'name' => 'Shipping Fee',
        'quantity' => 1,
        'unit_price' => 4900,
        'tax_rate' => 2500
    )
);


foreach ($cart as $item) {
    $create['cart']['items'][] = $item;
}

try {
    $order->create($create);
    $order->fetch();

    $orderID = $order['id'];

    echo sprintf('Order ID: %s', $orderID);
} catch (Klarna_Checkout_ApiErrorException $e) {
    var_dump($e->getMessage());
    var_dump($e->getPayload());
    die;
}

PHP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
cart = (
    {
        'quantity': 1,
        'reference': '123456789',
        'name': 'Klarna t-shirt',
        'unit_price': 12300,
        'discount_rate': 1000,
        'tax_rate': 2500
    }, {
        'quantity': 1,
        'type': 'shipping_fee',
        'reference': 'SHIPPING',
        'name': 'Shipping Fee',
        'unit_price': 4900,
        'tax_rate': 2500
    }
)

create_data = {}
create_data["cart"] = {"items": []}

for item in cart:
    create_data["cart"]["items"].append(item)

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
Dim item1
Set item1 = Server.CreateObject("Scripting.Dictionary")
item1.Add "reference", "123456789"
item1.Add "name", "Klarna t-shirt"
item1.Add "quantity", 2
item1.Add "unit_price", 12300
item1.Add "discount_rate", 1000
item1.Add "tax_rate", 2500

Dim item2
Set item2 = Server.CreateObject("Scripting.Dictionary")
item2.Add "type", "shipping_fee"
item2.Add "reference", "SHIPPING"
item2.Add "name", "Shipping Fee"
item2.Add "quantity", 1
item2.Add "unit_price", 4900
item2.Add "discount_rate", 2500
item2.Add "tax_rate", 2500

Dim cartItems(1)
Set cartItems(0) = item1
Set cartItems(1) = item2

Dim cart
Set cart = Server.CreateObject("Scripting.Dictionary")
cart.Add "items", cartItems

Dim data
Set data = Server.CreateObject("Scripting.Dictionary")
data.Add "cart", cart

Asp

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
var cartItems = new List<Dictionary<string, object>>
{
    new Dictionary<string, object>
        {
            { "reference", "123456789" },
            { "name", "Klarna t-shirt" },
            { "quantity", 2 },
            { "unit_price", 12300 },
            { "discount_rate", 1000 },
            { "tax_rate", 2500 }
        },
    new Dictionary<string, object>
        {
            { "type", "shipping_fee" },
            { "reference", "SHIPPING" },
            { "name", "Shipping Fee" },
            { "quantity", 1 },
            { "unit_price", 4900 },
            { "tax_rate", 2500 }
        }
};
var cart = new Dictionary<string, object> { { "items", cartItems } };

var data = new Dictionary<string, object>
{
    { "cart", cart }
};

2. Configure the checkout order

Change the configuration to reflect your website settings. These are the items you should configure:

Specify the merchant ID (EID) and shared secret that you received when you applied for API credentials.
Set the currency, language and country to be used.
Add URIs to where you host different pages used by Klarna Checkout.

Find out more about the different configurations in our API reference .

Note: If a checkout session already exists, you should use the already configured order in that session instead of adding the configuration data again to provide a better user experience.

Optimize the checkout for returning customers

When you render the checkout snippet you may add data about the consumer. We recommend using this feature for consumers who log into an account on your page where you already have stored data about the consumer. If you choose to add consumer data, the consumer will not need to re-enter the data into the checkout, and your conversion will increase. In the API resource structure you will find what data you can add (marked as Optional (O) during checkout_incomplete)

Note: If you are working with the SmartPost delivery option in Finland, then the Phone number entered in Klarna checkout needs to be used for sending the SmartPost SMS PIN. The SmartPost address shall be sent to Klarna as a “shipping option”

Note: when purchase_country is DE, two links to merchant terms is available in the checkout GUI (see image below). The general terms link (Den AGB) points directly to terms_uri. The cancellation rights link (Widerrufsrecht) points at the terms_uri with the anchor #cancellation_right added. (e.g. http://example.com/terms.html#cancellation_right ). You should make sure the cancellation rights can be found in your general terms and add the anchor to the page. German law requires that a direct link to cancellation rights is available in the checkout.

DE,AT

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
final Map<String, Object> merchant = new HashMap<String, Object>() {
    {
        put("id", "InsertYourEID");
        put("back_to_store_uri", "http://example.com");
        put("terms_uri", "http://example.com/terms.html");
        put("checkout_uri", "http://example.com/checkout.jsp");
        put("confirmation_uri",
                "http://example.com/thank-you.jsp"
                + "?klarna_order_id={checkout.order.id}");
        put("push_uri",
                "http://example.com/push.jsp"
                + "?klarna_order_id={checkout.order.id}");
    }
};

data.put("purchase_country", "SE");
data.put("purchase_currency", "SEK");
data.put("locale", "sv-se");
data.put("merchant", merchant);

Java

1
2
3
4
5
6
7
8
9
10
11
12
13
$create['purchase_country'] = 'SE';
$create['purchase_currency'] = 'SEK';
$create['locale'] = 'sv-se';
// $create['recurring'] = true;
$create['merchant'] = array(
    'id' => 'InsertYourEID',
    'terms_uri' => 'http://example.com/terms.html',
    'checkout_uri' => 'http://example.com/checkout.php',
    'confirmation_uri' => 'http://example.com/confirmation.php' .
        '?klarna_order_id={checkout.order.id}',
    'push_uri' => 'http://example.com/push.php' .
        '?klarna_order_id={checkout.order.id}'
);

PHP

1
2
3
4
5
6
7
8
9
10
11
12
13
create_data['purchase_country'] = 'SE'
create_data['purchase_currency'] = 'SEK'
create_data['locale'] = 'sv-se'
create_data['merchant'] = {
    'id': 'InsertYourEID',
    'back_to_store_uri': 'http://example.com',
    'terms_uri': 'http://example.com/terms.html',
    'checkout_uri': 'http://example.com/checkout',
    'confirmation_uri': ('http://example.com/thank-you' +
                        '?klarna_order_id={checkout.order.id}'),
    'push_uri': ('http://example.com/push' +
                '?klarna_order_id={checkout.order.id}')
}

Python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Dim merchant
Set merchant = Server.CreateObject("Scripting.Dictionary")
merchant.Add "id", "InsertYourEID"
merchant.Add "back_to_store_uri", "http://example.com"
merchant.Add "terms_uri", "http://example.com/terms.asp"
merchant.Add "checkout_uri", "https://example.com/checkout.asp"
merchant.Add "confirmation_uri", _
    "https://example.com/thankyou.asp?klarna_order_id={checkout.order.id}"
merchant.Add "push_uri", _
    "https://example.com/push.asp?klarna_order_id={checkout.order.id}"

data.Add "purchase_country", "SE"
data.Add "purchase_currency", "SEK"
data.Add "locale", "sv-se"
data.Add "merchant", merchant

ASP

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
var merchant = new Dictionary<string, object>
    {
        { "id", "InsertYourEID" },
        { "back_to_store_uri", "http://example.com" },
        { "terms_uri", "http://example.com/terms.aspx" },
        {
            "checkout_uri",
            "https://example.com/checkout.aspx"
        },
        {
            "confirmation_uri",
            "https://example.com/thankyou.aspx" +
            "?klarna_order_id={checkout.order.id}"
        },
        {
            "push_uri",
            "https://example.com/push.aspx" +
            "?klarna_order_id={checkout.order.id}"
        }
    };

data.Add("purchase_country", "SE");
data.Add("purchase_currency", "SEK");
data.Add("locale", "sv-se");
data.Add("merchant", merchant);

3. Create a checkout order

When all configuration data and the cart items have been set, it’s time to create an order in Klarna’s system.

Note: If a checkout session already exists you should use the order in that session instead of creating a new one.

1
2
3
4
IConnector connector = Connector.create(
    "sharedSecret", IConnector.TEST_BASE_URL);
Order order = new Order(connector);
order.create(data);

Java

1
2
3
4
5
6
$connector = Klarna_Checkout_Connector::create(
    'sharedSecret',
    Klarna_Checkout_Connector::BASE_TEST_URL
);
$order = new Klarna_Checkout_Order($connector);
$order->create($create);

PHP

1
2
3
connector = klarnacheckout.create_connector('shared_secret', klarnacheckout.BASE_TEST_URL)
order = klarnacheckout.Order(connector)
order.create(create_data)

Python

1
2
3
4
5
6
Dim connector : Set connector = CreateConnector(sharedSecret)
connector.SetBaseUri KCO_TEST_BASE_URI

Dim order : Set order = CreateOrder(connector)

order.Create data

ASP

1
2
3
var connector = Connector.Create("sharedSecret", Connector.TestBaseUri);
Order order = new Order(connector);
order.Create(data);

4. Render the checkout snippet

You should now fetch the order from Klarna’s system and store the order ID in the session. The checkout order now contains an HTML snippet under the gui.snippet property. You should extract the HTML snippet and display it on your checkout page.

1
2
3
4
5
6
7
8
9
10
order.fetch();

// Store checkout session.
// session.put("klarna_order_id", order.get("id"));

Map<String, Object> gui = (Map<String, Object>) order.get("gui");
String snippet = (String) gui.get("snippet");

// Output the snippet on your page. Assuming out is your PrintWriter.
out.println(String.format("<div>%s</div>", snippet));

Java

1
2
3
4
5
6
7
8
$order->fetch();

// Store location of checkout session
$_SESSION['klarna_order_id'] = $orderID = $order['id'];

// Display checkout
$snippet = $order['gui']['snippet'];
echo "<div>{$snippet}</div>";

PHP

1
2
3
4
5
6
7
order.fetch()

# Store order id of checkout session
session['klarna_order_id'] = order['id']

# Display checkout
print "<div>%s</div>" % (order["gui"]["snippet"])

Python

1
2
3
4
5
6
7
8
9
10
11
order.Fetch

Dim resourceData : Set resourceData = order.Marshal()

' Store location of checkout session in session object.
Session("klarna_order_id") = resourceData.id

' Display checkout
Dim snippet : snippet = resourceData.gui.snippet

Response.Write("<div>" & snippet & "</div>")

ASP

1
2
3
4
5
6
7
8
9
10
order.Fetch();

// Store order id of checkout in session object.
// session["klarna_order_id"] = order.GetValue("id") as string;

// Display checkout
var gui = order.GetValue("gui") as JObject;
var snippet = gui["snippet"];

Response.Write(string.Format("<div>{0}</div>", snippet));

This is what it should look like:

5. Update ongoing order

This tutorial is based on the update example file found in Klarna’s client libraries. You must specify the shared secret that you received when you applied for API credentials.

Retrieve the order

Use the checkout order ID stored in the session to fetch the order from Klarna.

1
2
3
4
5
6
7
8
9
10
11
IConnector connector = Connector.create(
        "sharedSecret", IConnector.TEST_BASE_URL);

// This is just a placeholder for the example.
// For example in jsp you could do
// String orderID = (String) request.getParameter("klarna_order_id");
String orderID = "12345";

Order order = new Order(connector, orderID);

order.fetch();

Java

1
2
3
4
5
6
7
8
9
10
$sharedSecret = 'sharedSecret';
$orderID = $_SESSION['klarna_order_id'];

$connector = Klarna_Checkout_Connector::create(
    $sharedSecret,
    Klarna_Checkout_Connector::BASE_TEST_URL
);

$order = new Klarna_Checkout_Order($connector, $orderID);
$order->fetch();

PHP

1
2
3
4
5
6
7
8
9
10
# Instance of the HTTP library that is being used in the server
request = {}

order_id = request['klarna_order_id']

connector = klarnacheckout.create_connector('shared_secret',
                                            klarnacheckout.BASE_TEST_URL)

order = klarnacheckout.Order(connector, order_id)
order.fetch()

Python

1
2
3
4
5
6
7
8
9
10
11
' Create connector
Dim connector : Set connector = CreateConnector("sharedSecret")
connector.SetBaseUri KCO_TEST_BASE_URI

' Retrieve order id from query string.
Dim orderID : orderID = Request.QueryString("klarna_order_id")

Dim order : Set order = CreateOrder(connector)
order.ID orderID

order.Fetch

ASP

1
2
3
4
5
6
7
8
9
var connector = Connector.Create("sharedSecret", Connector.TestBaseUri);

// Retrieve order id from query string.
// var orderId = Request.QueryString["klarna_order_id"] as string;
var orderId = "1245";

var order = new Order(connector, orderId);

order.Fetch();

Update the order

You should now update the checkout order to reflect the changes that the consumer has made to the cart. If you use the example code found in our client libraries, it will update the quantity of “Klarna t-shirt” to 4.

<TabsContainer> <Tab label=‘Java’ name=‘Java’ defaultChecked> <markdown> ```java final Map<String, Object> cart = new HashMap<String, Object>() { { put(“items”, new ArrayList<HashMap<String, Object>>() { { add(new HashMap<String, Object>() { { put(“quantity”, 2); put(“reference”, “123456789”); put(“name”, “Klarna t-shirt”); put(“unit_price”, 12300); put(“discount_rate”, 1000); put(“tax_rate”, 2500); } }); add(new HashMap<String, Object>() { { put(“quantity”, 1); put(“type”, “shipping_fee”); put(“reference”, “SHIPPING”); put(“name”, “Shipping Fee”); put(“unit_price”, 4900); put(“tax_rate”, 2500); } }); } }); } };

        // Reset cart
        Map<String, Object> data = new HashMap<String, Object>() {
            {
                put("cart", cart);
            }
        };

        order.update(data);
        ```
    </markdown>
</Tab>
<Tab label='PHP' name='PHP'>
    <markdown>
        ```php
        $cart = array(
            array(
                'reference' => '123456789',
                'name' => 'Klarna t-shirt',
                'quantity' => 4,
                'unit_price' => 12300,
                'discount_rate' => 1000,
                'tax_rate' => 2500
            ),
            array(
                'type' => 'shipping_fee',
                'reference' => 'SHIPPING',
                'name' => 'Shipping Fee',
                'quantity' => 1,
                'unit_price' => 4900,
                'tax_rate' => 2500
            )
        );

        // Reset cart
        $update = array();
        $update['cart']['items'] = array();

        foreach ($cart as $item) {
            $update['cart']['items'][] = $item;
        }

        $order->update($update);
        ```
    </markdown>
</Tab>
<Tab label='Python' name='Python'>
    <markdown>
        ```python
        cart = (
            {
                'quantity': 1,
                'reference': '123456789',
                'name': 'Klarna t-shirt',
                'unit_price': 12300,
                'discount_rate': 1000,
                'tax_rate': 2500
            }, {
                'quantity': 1,
                'type': 'shipping_fee',
                'reference': 'SHIPPING',
                'name': 'Shipping Fee',
                'unit_price': 4900,
                'tax_rate': 2500
            }
        )

        # Reset cart
        data = {'cart': []}
        data["cart"] = {"items": []}

        for item in cart:
            data["cart"]["items"].append(item)

        order.update(data)
        ```
    </markdown>
</Tab>
<Tab label='ASP' name='ASP'>
    <markdown>
        ```asp
        ' Cart
        Dim item1
        Set item1 = Server.CreateObject("Scripting.Dictionary")
        item1.Add "reference", "123456789"
        item1.Add "name", "Klarna t-shirt"
        item1.Add "quantity", 2
        item1.Add "unit_price", 12300
        item1.Add "discount_rate", 1000
        item1.Add "tax_rate", 2500

        Dim item2
        Set item2 = Server.CreateObject("Scripting.Dictionary")
        item2.Add "type", "shipping_fee"
        item2.Add "reference", "SHIPPING"
        item2.Add "name", "Shipping Fee"
        item2.Add "quantity", 1
        item2.Add "unit_price", 4900
        item2.Add "tax_rate", 2500

        Dim cartItems(1)
        Set cartItems(0) = item1
        Set cartItems(1) = item2

        Dim cart
        Set cart = Server.CreateObject("Scripting.Dictionary")
        cart.Add "items", cartItems

        ' Reset cart
        Dim data
        Set data = Server.CreateObject("Scripting.Dictionary")
        data.Add "cart", cart

        order.Update data
        ```
    </markdown>
</Tab>
<Tab label='C#' name='C#'>
    <markdown>
        ```csharp
        var cartItems = new List<Dictionary<string, object>>
        {
            new Dictionary<string, object>
                {
                    { "reference", "123456789" },
                    { "name", "Klarna t-shirt" },
                    { "quantity", 2 },
                    { "unit_price", 12300 },
                    { "discount_rate", 1000 },
                    { "tax_rate", 2500 }
                },
            new Dictionary<string, object>
                {
                    { "type", "shipping_fee" },
                    { "reference", "SHIPPING" },
                    { "name", "Shipping Fee" },
                    { "quantity", 1 },
                    { "unit_price", 4900 },
                    { "tax_rate", 2500 }
                }
        };

var cart = new Dictionary<string, object> { { "items", cartItems } };

// Reset cart
var data = new Dictionary<string, object> { { "cart", cart } };

order.Update(data);
        ```
    </markdown>
</Tab>

</TabsContainer>

Suspend and resume

This is how you suspend and resume the checkout to reflect an updated order in the consumer’s iframe. You will do this by first suspending the Klarna Checkout while you do behind-the-scenes updates to the order. When you are done with these updates, you will resume the checkout.

An order is valid for 48 hours and can be accessed only using the same API credentials used to create the order.

1. Suspend the checkout

Suspending the checkout puts it in a waiting state, preventing consumer input. A loading indicator is rendered on top of the iframe indicating to the consumer that the checkout is loading.

You will do this by issuing a Javascript command, as you can see in the code example below:

1
2
3
window._klarnaCheckout(function (api) {
    api.suspend();
});

2.Update a Checkout order

Update the order as you did in the update an ongoing order tutorial above.

3. Resume the checkout

Resuming the checkout forces it to fetch the most recent order data from Klarna. The loading indicator will disappear and the consumer can continue to fill in the form. The amount presented in the checkout will now reflect the new order total.

1
2
3
window._klarnaCheckout(function (api) {
    api.resume();
});

What’s next?

You have integrated Klarna Checkout into your checkout page.

The next step is to learn how to render the confirmation snippet .