1. Obtain an Instant Shopping Button Key (server-side)

You complete this step leveraging the Instant Shopping Button Keys REST API from your server-side

After you complete this step you will have a static Button key ready to be used anywhere and offer a purchase flow through Instant Shopping. The button is static in the sense that it includes all the information necessary to identify you as a merchant, do the necessary setup in terms of e.g. purchase country, locale, etc., specify the product(s) being sold, define the shipping options, and bootstrap the client-side application.

Instant Shopping Button Key Generation API

An example of a request to the service in order to obtain a Button key is given below. Note that the order_amount and order_tax_amount will be calculated by the service.

Note: Read about Klarna’s API URLs to know the base URL, and about Authentication to know how to authenticate when calling our REST API. More detailed documentation on the Instant Shopping orders API is available in the API documentation.

Request to generate a Button key

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
POST /instantshopping/v1/buttons
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  "purchase_country": "< mandatory, country, e.g. SE >",
  "purchase_currency": "< mandatory, currency, e.g. SEK >",
  "locale": "< mandatory, locale, e.g. en-SE >",
  "merchant_urls": {
    "place_order": "< mandatory, URL of an endpoint at the merchant side, which will receive a ping to place an order. (must be https, max 2000 characters) >",
    "terms": "< mandatory, URL of a page on the merchant side describing the terms and conditions. (max 2000 characters) >",
    "confirmation": "< mandatory, URL of a page that the consumers will be redirected to after completing a purchase with Instant Shopping. (max 2000 characters) >",
    "push": "< optional, URL of an endpoint at the merchant side, which will receive a ping when an order is completed within Klarna's order management. (must be https, max 2000 characters) >",
    "notification": "< optional, URL of an endpoint at the merchant side, which will receive notifications on pending orders. (must be https, max 2000 characters) >",
    "update": "< optional, URL for applying price, shipping, tax and purchase currency updates as a result of an update. (must be https, max 2000 characters) >"
  },
  "order_lines": [{
    "type": "< mandatory, order line type., e.g. physical >",
    "reference": "< mandatory, article number, SKU or similar. >",
    "name": "< mandatory, descriptive item name, maximum 255 characters. >",
    "quantity": "< mandatory, Item quantity, non-negative, between 0 and 100000 >",
    "unit_price": "< mandatory, unit price including tax without applying discounts in minor units >",
    "tax_rate": "< mandatory, number, two implicit decimals>",
    "total_amount": "< mandatory, total amount includes tax and discount >",
    "total_discount_amount": "< mandatory, the discount amount in minor units, includes tax >",
    "total_tax_amount": "< mandatory, the total tax amount in minor units >",
    "image_url": "< mandatory, URL to a product image >"
  }],
  "shipping_options": [{ // optional
    "id": "< mandatory, option id, e.g. express >",
    "name": "< mandatory, option name, e.g. EXPRESS 1-2 Days >",
    "description": "< mandatory, helpful text, e.g. Delivery by 4:30 pm >",
    "price": "< mandatory, price including tax >",
    "tax_amount": "< mandatory, tax amount >",
    "tax_rate": "< mandatory, non-negative, in percent, two implicit decimals. i.e 2500 = 25% >",
    "preselected": "< optional, boolean >",
    "shipping_method": "< optional, PickUpStore | Home | BoxReg | BoxUnreg | PickUpPoint | Own >"
  }],
  "merchant_reference1": "< optional, used for storing merchant internal reference"
}

Upon success the response of this service will provide you the next URL to fetch the key. Response for created Button key

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
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": { /* ... */ },
  "purchase_country": "string",
  "purchase_currency": "string",
  "locale": "string",
  "merchant_reference1": "string",
  "merchant_reference2": "string",
  "merchant_data": "string",
  "options": { /*...*/ },
  "order_lines":  [ /*...*/ ],
  "shipping_options": [ /*...*/ ]
}

Further options with the Button Key Generation API

The Button Key Generation API supports further operations on Button keys, like retrieving and updating the stored configuration. More detailed information in the API documentation.

Retrieve the stored configuration of a Button key To retrieve the configuration of a Button key you need to perform a GET request to the endpoint providing the specific Button key in the path.

1
2
3
GET /instantshopping/v1/buttons/123e4567-e89b-12d3-a456-426655440000
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json

Update the stored configuration of a Button key To update the configuration of a Button key you need to perform a PUT request to the endpoint providing the specific Button key in the path and the options to update in the body.

1
2
3
4
5
6
PUT /instantshopping/v1/buttons/123e4567-e89b-12d3-a456-426655440000
Authorization: Basic pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/json
{
  /* updated setup options */
}

What’s next?

It’s time to use the button key you have just created and embed the Instant Shopping Button to the desired page.