How to use Instant Shopping for signing up for subscriptions

1. Setup a Merchant ID

The first step is to setup a Merchant ID and configure Klarna Payments with the suitable payment methods for the purpose of generating customer tokens. This configuration should be done for all the billing countries the merchant wants to use Instant Shopping for.

For the next steps you will need the Klarna API Credentials (you can generate new after logging in to the Merchant Portal)

2. Create a button key

You need to create a Button key which you can reuse for displaying Instant Shopping in multiple pages. This key is used to identify you as a merchant and also to link to some necessary configuration options.

Since this key can be reused for displaying Instant Shopping in multiple pages, it is advised that you generate it once and then store it somewhere within your system.

To create a key you can use the Instant Shopping Button Keys Service . An example of a request to this service is given below. Note that you need to use your API credentials to authenticate.

Request

1
2
3
4
5
6
7
8
POST /instantshopping/v1/buttons
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "merchant_urls": {
    "create_customer_token": "< mandatory, URL of an endpoint at the merchant side, which will receive a ping to approve the generation customer token. (must be https, max 2000 characters) >"
  }
}

Response

1
2
3
4
5
6
7
HTTP 201 Created
Content-Type: application/json
Location: /instantshopping/v1/buttons/123e4567-e89b-12d3-a456-426655440000
{
  "button_key": "123e4567-e89b-12d3-a456-426655440000",
  "merchant_urls": { /* ... */ }
}

3. Setup and Display Instant Shopping Button (client-side)

You complete this step from your client-side

After successfully completing this part you should see the Instant Shopping Button.

3.a. Add the Javascript SDK to the page

You will need to make sure that the Instant Shopping Button Javascript SDK is available on the page you want to display the Instant Shopping Button.

To do this add the following script tag as soon as possible in the page (e.g. <head>).

1
2
3
4
5
6
7
8
9
10
<script>
  window.klarnaAsyncCallback = function () {

    // This is where you start calling Instant Shopping JS SDK functions
    //
    // Klarna.InstantShopping.load({....})

  };
</script>
<script src="https://x.klarnacdn.net/instantshopping/lib/v1/lib.js" async></script>

3.b. Add a container for the Instant Shopping Button to the page

At this step you decide where you want to place the Instant Shopping button within the page by positioning the HTML container element.

It is important to add a data attribute named data-instance-id to this element, which will uniquely identify this button. Note that you will refer to the value of this attribute when you use the JavaScript API and need to provide the setup.instance_id option. This is particularly necessary if you want to show multiple buttons on the same page. In that case each data-instance-id should be different and unique for this page.

1
  <klarna-instant-shopping data-instance-id="button-123abc456" />

3.c. Configure and display the Instant Shopping Button

You will now need to provide all the information necessary to support the purchase flow. This information refers to the product(s) being in the cart (together with possible discounts, etc.), relevant shipping options, locale, currency, etc.

Note that you will use the button key created from the previous step.

Below you see an example of the configuration options that are necessary for the consumer flow. Please note that the order_amount and order_tax_amount will be calculated by the service.

Consult our Javascript Docs for more information.

3.c.1 Load the Instant Shopping

The klarnaAsyncCallback is executed as soon as the Instant Shopping Javascript SDK is ready.

You should define this function before the script tag for fetching lib.js (see 3.a) and as early as possible in the page, e.g. head.

In the example below we consider that this Instant Shopping flow is selling subscriptions of variant durations.

Important: You need to provide a localized text describing the details of the subscription (cost, duration, start, end dates) by setting up the tokenization.description property.

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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
window.klarnaAsyncCallback = function () {
  window.Klarna.InstantShopping.load({
    "setup": {
      "instance_id": "button-123abc456",
      "key": "123e4567-e89b-12d3-a456-426655440000",
      "environment": "production",
      "region": "eu"
    },
    "tokenization": {
      "description": "Legal text, describing the conditions of this subscription. E.g. Read frist two months for free, then the monthly cost until further notice."
    },
    "purchase_country": "SE",
    "purchase_currency": "SEK",
    "locale": "en-SE",
    "merchant_urls": {
      "terms": "https://example.com/terms",
      "confirmation": "https://example.com/subscription-confirmation.page"
    },
    "items": [
      {
        "type": "digital",
        "reference": "subscription-3m",
        "name": "3 month subscription at 29.99/month",
        "unit_price": 2999,
        "tax_rate": 0,
        "total_amount": 2999,
        "total_tax_amount": 0,
        "image_url": "https:/example.coma/subscription-logo.svg",
        "group_identifier": "subscription",
        "product_attributes": [
          {
            "identifier": "suscription_type",
            "identifier_label": "Subscription type",
            "value": "3m",
            "value_label": "3 month subscription at 29.99/month"
          }
        ]
      },
      {
        "type": "digital",
        "reference": "subscription-6m",
        "name": "6 month subscription at 19.99/month",
        "unit_price": 1999,
        "tax_rate": 0,
        "total_amount": 1999,
        "total_tax_amount": 0,
        "image_url": "https:/example.coma/subscription-logo.svg",
        "group_identifier": "subscription",
        "product_attributes": [
          {
            "identifier": "suscription_type",
            "identifier_label": "Subscription type",
            "value": "6m",
            "value_label": "6 month subscription at 19.99/month"
          }
        ]
      },
      {
        "type": "digital",
        "reference": "subscription-12m",
        "name": "12 month subscription at 9.99/month",
        "unit_price": 999,
        "tax_rate": 0,
        "total_amount": 999,
        "total_tax_amount": 0,
        "image_url": "https:/example.coma/subscription-logo.svg",
        "group_identifier": "subscription",
        "product_attributes": [
          {
            "identifier": "suscription_type",
            "identifier_label": "Subscription type",
            "value": "12m",
            "value_label": "12 month subscription at 9.99/month"
          }
        ]
      }
    ]
  }, function (response) {
    console.log('Klarna.InstantShopping.load callback with data:' + JSON.stringify(response))
  })
}

4. Approving/ Declining the customer token

When the consumer has chosen to finalize the flow, our server-side will ping you at the merchant_urls.create_customer_token endpoint, and prompt you to ask for the generation of a customer token. You do not need to act on this request, you can merely respond with HTTP 200 and proceed.

Receive a ping

Request

At this point we expect that you validate the request body and decide whether you will approve/decline.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
POST <merchant_urls.create_customer_token>
Content-Type: application/json
{
  button_key: <kis_button_key>,
  authorization_token: <kis_auth_token>,
  order: {
    order_lines: <the product the customer saw in KIS FE>,
    locale: '',
    purchase_currency: ''
  },
  customer_token_details: {
    billing_address: {},
    customer: {}
  }
}

Response

The response to this request is not important, you can reply with HTTP 200.

Approve

To approve and receive a customer token you will need to perform a POST to Instant Shopping API, as shown in the example below. You will use the authorization_token from the ping request body above.

1
2
3
POST /instantshopping/v1/authorizations/{authorization_token}/customer-tokens
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

Response

1
2
3
4
5
6
HTTP 200 OK
Content-Type: application/json
Location: /instantshopping/v1/authorizations/{authorization_token}/customer-tokens
{
  token_id: '<kp_token>'
}
Placing order

To place the order you will need to use the response above in KP for each recurring payment. For more information on the KP place order, you can visit Klarna Payments

Decline

To decline you will need to perform a DELETE to Instant Shopping API, as shown in the example below. You will use the authorization_token from the ping request body above.

1
2
3
DELETE /instantshopping/v1/authorizations/{authorization_token}
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json