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

Introduction

The Klarna Checkout REST API is the underlying interface for all our available client libraries. This reference guide was created for those who are developing for platforms currently not supported by our client libraries, or those who are interested in diving into the details of our API.

Entry points

The Klarna Checkout API can be accessed from the following entry points, depending on the environment you are working in:

https://checkout.klarna.com/checkout/orders - For transactions in the live environment

https://checkout.testdrive.klarna.com/checkout/orders - For test transactions in Klarna’s testing environment.

HTTPS vs HTTP

To help ensure data security, only HTTPS is allowed. HTTP is not supported.

JSON, Unicode

JSON is used across all communications as the syntax of the media-types. Only JSON’s default UTF-8 encoding is supported.

Authorization

Every API request has to be authenticated by using the Authentication HTTP request header. Only a proprietary Klarna authentication scheme is supported, in the format of Klarna authorization header.

The authorization header is calculated for each request using these steps of this formula: base64(hex(sha256 (request_payload + shared_secret))), where

  • request_payload is the payload of the request, or an empty string for GET requests
  • shared_secret is the secret key assigned to your EID by Klarna

Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA==

Order resource

Legend

O, optional

M, mandatory

R, read only

resource properties

NameTypeDescription
Name
id
Type
string
R
Description
Unique identifier of the Klarna Checkout Order
Name
purchase_country
Type
string
M
Description
Country in which the purchase is done (ISO-3166-alpha2)
Name
purchase_currency
Type
string
M
Description
Currency in which the purchase is done (ISO-4217)
Name
locale
Type
string
M
Description
Locale indicative for language & other location-specific details (RFC1766)
Name
status
Type
string
R *
Description
Status. checkout_incomplete by default, alternatively checkout_complete, created
Name
reference
Type
string
R
Description
End-consumer friendly reference
Name
reservation
Type
string
R
Description
Reservation number to be used in the XML-RPC API
Name
recurring
Type
boolean
O
Description
Only in Sweden, Norway and Finland: Indicates whether this purchase is a recurring order
Name
recurring_token
Type
string
R
Description
Token to be used when creating recurring orders
Name
merchant_reference
Type
merchant reference object
O *
Description
Merchant references
Name
billing_address
Type
address object
R
Description
The billing address
Name
shipping_address
Type
address object
O
Description
The shipping address
Name
cart
Type
cart object
M
Description
The cart
Name
customer
Type
customer object
O
Description
Information about the liable customer of the order.
Name
gui
Type
gui object
O
Description
The gui object
Name
merchant
Type
merchant object
M
Description
Merchant related information.
Name
attachment
Type
attachment object
O
Description
Additional purchase information required for some industries.
Name
external_payment_methods
Type
array of external payment method objects
O
Description
External payment methods
Name
external_checkouts
Type
array of external checkout objects
O
Description
External checkout providers
Name
options
Type
options object
O
Description
Options for this purchase, read more here .
Name
started_at
Type
string
R
Description
Timestamp of when the Checkout started (ISO-8601)
Name
completed_at
Type
string
R
Description
Timestamp of when the Checkout was completed (ISO-8601)
Name
created_at
Type
string
R
Description
Timestamp of when the Order was created (ISO-8601)
Name
last_modified_at
Type
string
R
Description
Timestamp of when the Checkout was last modified (ISO-8601)
Name
expires_at
Type
string
R
Description
Timestamp of when the Checkout will expire (ISO-8601)
Name
merchant_requested
Type
object
R
Description
Stores merchant requested data. e.g. the state of the optional additional_checkbox

* When the order status is checkout_complete or created all properties become read only, except status and merchant_reference.

merchant reference object properties

VariableTypeDescription
Variable
orderid1
Type
string
O
Description
Used for storing merchant’s internal order number or other reference.
Variable
orderid2
Type
string
O
Description
Used for storing merchant’s internal order number or other reference.

address object properties

VariableTypeDescription
Variable
given_name
Type
string
R
Description
First name
Variable
family_name
Type
string
R
Description
Last name
Variable
care_of
Type
string
R
Description
c/o
Variable
reference
Type
string
O
Description
Only for B2B orders. Reference information entered by the customer for this B2B order.
Variable
organization_name
Type
string
R
Description
Only for B2B orders. The name of the organization placing the order.
Variable
street_address
Type
string
R
Description
Only in Sweden, Norway and Finland: Street address (street name, street number, street extension)
Variable
street_name
Type
string
R
Description
Only in Germany and Austria: Street name
Variable
street_number
Type
string
R
Description
Only in Germany and Austria**:** Street number
Variable
postal_code
Type
string
O
Description
Postal code
Variable
city
Type
string
R
Description
City
Variable
country
Type
string
R
Description
Country (ISO-3166 alpha)
Variable
email
Type
string
O
Description
E-mail address
Variable
phone
Type
string
R
Description
Phone number
Variable
title
Type
string
R
Description
Only in Germany and Austria**:** The customer’s title, possible values are “Herr” and “Frau”

cart object properties

VariableTypeDescription
Variable
total_price_excluding_tax
Type
integer
R
Description
Total price (excluding tax) in cents
Variable
total_tax_amount
Type
integer
R
Description
Total tax amount in cents
Variable
total_price_including_tax
Type
integer
R
Description
Total price (including tax) in cents
Variable
items
Type
array of cart item objects
M
Description
List of cart items

cart item object properties

VariableTypeDescription
Variable
type
Type
string
O
Description
Type. physical by default, alternatively discount, shipping_fee
Variable
ean
Type
string
O
Description
The item’s International Article Number. Please note this property is currently not returned when fetching the full order resource.
Variable
reference
Type
string
M
Description
Reference, usually the article number
Variable
name
Type
string
M
Description
Name, usually a short description
Variable
uri
Type
string
O
Description
Item product page URI. Please note this property is currently not returned when fetching the full order resource.
Variable
image_uri
Type
string
O
Description
Item image URI. Please note this property is currently not returned when fetching the full order resource.
Variable
quantity
Type
integer
M
Description
Quantity
Variable
unit_price
Type
integer
M
Description
Unit price in cents, including tax
Variable
total_price_excluding_tax
Type
integer
R
Description
Total price (excluding tax) in cents
Variable
total_tax_amount
Type
integer
R
Description
Total tax amount, in cents
Variable
total_price_including_tax
Type
integer
R
Description
Total price (including tax) in cents
Variable
discount_rate
Type
integer
O
Description
Percentage of discount, multiplied by 100 and provided as an integer. i.e. 9.57% should be sent as 957
Variable
tax_rate
Type
integer
M
Description
Percentage of tax rate, multiplied by 100 and provided as an integer. i.e. 13.57% should be sent as 1357

customer object properties

VariableTypeDescription
Variable
date_of_birth
Type
string
O
Description
If provided by customer, or retrieved from national ID. The customer’s birthdate (YYYY-MM-DD)
Variable
gender
Type
string
O
Description
Retrieved from national ID or billing_address.title in Germany. ‘female’ or ‘male’
Variable
type
Type
string
R
Description
Type. The default supported value is ‘person’. If B2B is enabled for the e-store ID, the value may be ‘organization’.
Variable
organization_registration_id
Type
string
O
Description
For B2B, this field is used for the organization’s official registration id (Organization number).

gui object properties

Note: The gui_object cannot be changed. It can only be set in the the create operation.

VariableTypeDescription
Variable
layout
Type
string
O
Description
Layout. desktop by default, alternatively mobile
Variable
options
Type
array of strings
O
Description
An array of options to define the checkout behaviour. Supported options disable_autofocus.
Variable
snippet
Type
string
R
Description
HTML snippet

merchant object properties

VariableTypeDescription
Variable
id
Type
string
M
Description
Unique identifier (EID)
Variable
terms_uri
Type
string
M
Description
URI of your terms and conditions
Variable
organization_terms_uri
Type
string
O
Description
URI of your terms and conditions for B2B purchases/organizations (may be used in the B2B flow)
Variable
cancellation_terms_uri
Type
string
O
Description
URI of the cancellation terms
Variable
checkout_uri
Type
string
M
Description
URI of your checkout page
Variable
confirmation_uri
Type
string
M
Description
URI of your confirmation page
Variable
push_uri
Type
string
M
Description
URI of your push-notification page
Variable
validation_uri
Type
string
O
Description
URI of your validation page, see validate a checkout order .
Variable
back_to_store_uri
Type
string
O
Description
URI of your store page. Used on the settlement page.

attachment object properties

VariableTypeDescription
Variable
body
Type
string
M
Description
The attachment body.
Variable
content_type
Type
string
M
Description
The content type of the body property.

A list of available attachment types can be found here .

external payment method object properties

VariableTypeDescription
Variable
name
Type
string
M
Description
Payment method name
Variable
redirect_uri
Type
string
M
Description
URI of external payment method page
Variable
image_uri
Type
string
O
Description
URI of external payment method image (https://)
Variable
fee
Type
integer
O
Description
Fee in cents, including tax
Variable
description
Type
string
O
Description
500 character limit. Links can be set with the Markdown syntax Text

external checkout object properties

VariableTypeDescription
Variable
name
Type
string
M
Description
Checkout name
Variable
redirect_uri
Type
string
M
Description
URI of external payment method page
Variable
image_uri
Type
string
M
Description
URI of external payment method image (https://)
Variable
fee
Type
integer
O
Description
Fee in cents, including tax

options object properties

VariableTypeDescription
Variable
color_button
Type
string
O
Description
Only hexadecimal values are allowed.
Variable
color_button_text
Type
string
O
Description
Only hexadecimal values are allowed.
Variable
color_checkbox
Type
string
O
Description
Only hexadecimal values are allowed.
Variable
color_checkbox_checkmark
Type
string
O
Description
Only hexadecimal values are allowed.
Variable
color_header
Type
string
O
Description
Only hexadecimal values are allowed.
Variable
color_link
Type
string
O
Description
Only hexadecimal values are allowed.
Variable
shipping_details
Type
string
O
Description
Shipping information displayed on the confirmation page. Maximum 70 characters.
Variable
phone_mandatory
Type
boolean
O
Description
Making the phone field mandatory (Only available in Germany and Austria)
Variable
allow_separate_shipping_address
Type
boolean
O
Description
To allow separate shipping addresses
Variable
packstation_enabled
Type
boolean
O
Description
Enable packstation (Only available in Germany)
Variable
allowed_customer_types
Type
list of string
O
Description
List of the allowed customer types. Allowed values are ‘person’ and ‘organization’ if B2B is enabled on the e-store ID.
Variable
date_of_birth_mandatory
Type
boolean
O
Description
Making the date of birth mandatory
Variable
additional_checkbox
Type
checkbox object
O
Description
Additional merchant defined checkbox. e.g. for Newsletter opt-in.
Variable
additional_merchant_terms
Type
string
O
Description
Additional merchant defined field. e.g. Extra terms and conditions to show.

checkbox object properties

VariableTypeDescription
Variable
text
Type
string
M
Description
Text that will be displayed to the consumer aside the checkbox. (max 255 characters). This text can contain links using the format Link text .
Variable
checked
Type
boolean
M
Description
Default state of the additional checkbox. It will use this value when loaded for the first time.
Variable
required
Type
boolean
M
Description
Whether it is required for the consumer to check the additional checkbox box or not in order to complete the purchase.

merchant_requested object properties

VariableTypeDescription
Variable
additional_checkbox
Type
boolean
R
Description
Informs whether the the additional_checkbox is checked or not, when applicable.

Errors

Klarna uses conventional HTTP response codes to indicate success or failure of an API call.

Status codeDescription
Status code
200
OK
Description
The request was successful.
Status code
201
Created
Description
The request was successful and created a new resource at the URI described by the Content-Location response header
Status code
400
Bad Request
Description
The request did not pass validation due to syntax or semantic errors. Error message should indicate the error.
Status code
401
Unauthorized
Description
Authentication failed due to an invalid or missing Authentication request header.
Status code
403
Forbidden
Description
The server refused to fulfil it.
Status code
404
Not Found
Description
There is no resource matching the request URI.
Status code
405
Method Not Allowed
Description
The resource did not expected the request method.
Status code
406
Not Acceptable
Description
The server cannot fulfil the Accept request header.
Status code
415
Media Type Not Supported
Description
The server does not support the media-type specified by the Content-Type request header.

Versioning

The Klarna Checkout API is versioned through custom media types. When we make changes to the API which are not backwards compatible, we will increment the version number in the media type.

Current version: application/vnd.klarna.checkout.aggregated-order-v2+json

Supported locales

The locale configuration in Klarna Checkout affects the iframe language and all further communication made between Klarna and the consumer.

This table specifies the supported combinations of country, currently and locale.

CountryLanguagepurchase_countrypurchase_currencylocale
Country
Sweden
Language
Swedish
purchase_country
SE
purchase_currency
SEK
locale
sv-se
Country
Sweden
Language
English
purchase_country
SE
purchase_currency
SEK
locale
en-us
Country
Finland
Language
Finnish
purchase_country
FI
purchase_currency
EUR
locale
fi-fi
Country
Finland
Language
Swedish
purchase_country
FI
purchase_currency
EUR
locale
sv-fi
Country
Finland
Language
English
purchase_country
FI
purchase_currency
EUR
locale
en-us
Country
Norway
Language
Norwegian
purchase_country
NO
purchase_currency
NOK
locale
nb-no
Country
Norway
Language
English
purchase_country
NO
purchase_currency
NOK
locale
en-us
Country
Germany
Language
German
purchase_country
DE
purchase_currency
EUR
locale
de-de
Country
Germany
Language
English
purchase_country
DE
purchase_currency
EUR
locale
en-us
Country
Austria
Language
German
purchase_country
AT
purchase_currency
EUR
locale
de-at
Country
Austria
Language
English
purchase_country
AT
purchase_currency
EUR
locale
en-us

Resources

Aggregated Order

Create

Overview

  • Description: Create a new Checkout Order resource
  • Request
  • Method: POST
  • URI: https://checkout.testdrive.klarna.com/checkout/orders
  • Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
  • Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json
  • Body: …
  • Response
  • Location: URI of the new Checkout Order resource

HTTP Request

Once the order is created, the order will contain a HTML snippet that needs to be embedded on your Checkout page.

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
POST /checkout/orders HTTP/1.1
Host: checkout.testdrive.klarna.com
Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json

{
    "merchant_reference": {
        "orderid1": "123456789",
        "orderid2": "123456789"
    },
    "purchase_country": "se",
    "purchase_currency": "sek",
    "locale": "sv-se",
    "cart": {
        "items": [
        {
            "reference": "123456789",
            "name": "Klarna t-shirt",
            "quantity": 2,
            "ean": "1234567890123",
            "uri": "http://example.com/product.php?123456789",
            "image_uri": "http://example.com/product_image.php?123456789",
            "unit_price": 12300,
            "discount_rate": 1000,
            "tax_rate": 2500
        },
        {
            "type": "shipping_fee",
            "reference": "SHIPPING",
            "name": "Shipping fee",
            "quantity": 1,
            "unit_price": 4900,
            "tax_rate": 2500
        }
        ]
    },
    "shipping_address": {
        "given_name": "Testperson-se",
        "family_name": "Approved",
        "street_address": "Stårgatan 1",
        "postal_code": "12345",
        "city": "Ankeborg",
        "country": "se",
        "email": "checkout@testdrive.klarna.com",
        "phone": "0765260000"
    },
    "gui": {
        "layout": "desktop"
    },
    "merchant": {
        "id": "0",
        "back_to_store_uri": "http://example.com",
        "terms_uri": "http://example.com/terms.php",
        "checkout_uri": "https://example.com/checkout.php",
        "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}"
    }
}

HTTP Response

1
2
3
HTTP/1.1 201 Created
Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json
Location: https://checkout.testdrive.klarna.com/checkout/orders/{id}

Read

Overview

HTTP Request

1
2
3
4
GET /checkout/orders/{id} HTTP/1.1
Host: checkout.testdrive.klarna.com
Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA==

HTTP Response

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
82
83
84
85
86
HTTP/1.1 200 OK
Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json

{
    "id": "1A2B3C4D5E6F1A2B3C4D5E6F",
    "merchant_reference": {
        "orderid1": "123456789",
        "orderid2": "123456789"
    },
    "purchase_country": "se",
    "purchase_currency": "sek",
    "locale": "sv-se",
    "status": "created",
    "reference": "Q1W2E3",
    "reservation": "123456789",
    "started_at": "2012-01-18T11:45:00+01:00",
    "completed_at": "2012-01-18T11:51:00+01:00",
    "created_at": "2012-01-18T11:52:00+01:00",
    "last_modified_at": "2012-01-18T11:52:00+01:00",
    "expires_at": "2012-02-01T11:52:00+01:00",
    "shipping_address": {
        "given_name": "Testperson-se",
        "family_name": "Approved",
        "care_of": "Testperson",
        "street_address": "Stårgatan 1",
        "postal_code": "12345",
        "city": "Ankeborg",
        "country": "se",
        "email": "checkout@testdrive.klarna.com",
        "phone": "0765260000"
    },
    "billing_address": {
        "given_name": "Testperson-se",
        "family_name": "Approved",
        "care_of": "Testperson",
        "street_address": "Stårgatan 1",
        "postal_code": "12345",
        "city": "Ankeborg",
        "country": "se",
        "email": "checkout@testdrive.klarna.com",
        "phone": "0765260000"
    },
    "cart": {
        "total_price_excluding_tax": 20280,
        "total_tax_amount": 6760,
        "total_price_including_tax": 27040,
        "items": [
        {
            "reference": "123456789",
            "name": "Klarna t-shirt",
            "quantity": 2,
            "unit_price": 12300,
            "discount_rate": 1000,
            "tax_rate": 2500,
            "total_price_excluding_tax": 16605,
            "total_tax_amount": 5535,
            "total_price_including_tax": 22140,
        },
        {
            "type": "shipping_fee",
            "reference": "SHIPPING",
            "name": "Shipping fee",
            "quantity": 1,
            "unit_price": 4900,
            "tax_rate": 2500,
            "total_price_excluding_tax": 3675,
            "total_tax_amount": 1225,
            "total_price_including_tax": 4900,
        }
        ]
    },
    "customer": {
        "type": "person",
    },
    "gui": {
        "layout": "desktop",
        "snippet": "..."
    },
    "merchant": {
        "id": "0",
        "terms_uri": "http://example.com/terms.php",
        "checkout_uri": "https://example.com/checkout.php",
        "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}"
    }
}

Update

Overview

  • Description: Update a Checkout Order resource
  • Request
  • Method: POST
  • URI: https://checkout.testdrive.klarna.com/checkout/orders/{id}
  • Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
  • Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json
  • Body:
  • Response
  • An updated representation of the Checkout Order

Please note: For orders in state checkout_complete, only the merchant_reference and status properties can be updated. For orders in state created, only the merchant_reference can be updated.

HTTP Request

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
POST /checkout/orders/{id} HTTP/1.1
Host: checkout.testdrive.klarna.com
Accept: application/vnd.klarna.checkout.aggregated-order-v2+json
Authorization: Klarna pwhcueUff0MmwLShJiBE9JHA==
Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json

{
    "merchant_reference": {
        "orderid1": "123456789",
        "orderid2": "123456789"
    },
    "purchase_country": "se",
    "purchase_currency": "sek",
    "locale": "sv-se",
    "cart": {
        "items": [
        {
            "reference": "123456789",
            "name": "Klarna t-shirt",
            "quantity": 4,
            "ean": "1234567890123",
            "uri": "http://example.com/product.php?123456789",
            "image_uri": "http://example.com/product_image.php?123456789",
            "unit_price": 12300,
            "discount_rate": 1000,
            "tax_rate": 2500
        },
        {
            "type": "shipping_fee",
            "reference": "SHIPPING",
            "name": "Shipping fee",
            "quantity": 1,
            "unit_price": 4900,
            "tax_rate": 2500
        }
        ]
    },
    "shipping_address": {
        "given_name": "Testperson-se",
        "family_name": "Approved",
        "street_address": "Stårgatan 1",
        "postal_code": "12345",
        "city": "Ankeborg",
        "country": "se",
        "email": "checkout@testdrive.klarna.com",
        "phone": "0765260000"
    },
    "gui": {
        "layout": "desktop"
    },
    "merchant": {
        "id": "0",
        "terms_uri": "http://example.com/terms.php",
        "checkout_uri": "https://example.com/checkout.php",
        "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}"
    }
}

HTTP Response

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
HTTP/1.1 200 OK
Content-Type: application/vnd.klarna.checkout.aggregated-order-v2+json

{
    "id": "1A2B3C4D5E6F1A2B3C4D5E6F",
    "merchant_reference": {
        "orderid1": "123456789",
        "orderid2": "123456789"
    },
    "purchase_country": "se",
    "purchase_currency": "sek",
    "locale": "sv-se",
    "status": "checkout_incomplete",
    "reference": "Q1W2E3",
    "reservation": "123456789",
    "started_at": "2012-01-18T11:45:00+01:00",
    "completed_at": "2012-01-18T11:51:00+01:00",
    "created_at": "2012-01-18T11:52:00+01:00",
    "last_modified_at": "2012-01-18T11:52:00+01:00",
    "expires_at": "2012-02-01T11:52:00+01:00",
    "shipping_address": {
        "given_name": "Testperson-se",
        "family_name": "Approved",
        "care_of": "Testperson",
        "street_address": "Stårgatan 1",
        "postal_code": "12345",
        "city": "Ankeborg",
        "country": "se",
        "email": "checkout@testdrive.klarna.com",
        "phone": "0765260000"
    },
    "cart": {
        "total_price_excluding_tax": 36885,
        "total_tax_amount": 12295,
        "total_price_including_tax": 49180,
        "items": [
        {
            "reference": "123456789",
            "name": "Klarna t-shirt",
            "quantity": 4,
            "unit_price": 12300,
            "discount_rate": 1000,
            "tax_rate": 2500,
            "total_price_excluding_tax": 33210,
            "total_tax_amount": 11070,
            "total_price_including_tax": 44280,
        },
        {
            "type": "shipping_fee",
            "reference": "SHIPPING",
            "name": "Shipping fee",
            "quantity": 1,
            "unit_price": 4900,
            "tax_rate": 2500,
            "total_price_excluding_tax": 3675,
            "total_tax_amount": 1225,
            "total_price_including_tax": 4900,
        }
        ]
    },
    "customer": {
        "type": "person",
    },
    "gui": {
        "layout": "desktop",
        "snippet": "..."
    },
    "merchant": {
        "id": "0",
        "terms_uri": "http://example.com/terms.php",
        "checkout_uri": "https://example.com/checkout.php",
        "confirmation_uri": "https://example.com/thankyou.php?sid=123&klarna_order={checkout.order.id}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.id}"
    }
}
This section only applies to the regions:
Sweden, Norway, Finland

Recurring Order

Create

Overview

  • Description: Create a new Recurring Checkout Order resource. You must first have created a aggregated order with the option “recurring” set to true and then use the recurring_token returned on the resource
  • Request
  • Method: POST
  • URI: https://checkout.testdrive.klarna.com/checkout/recurring/{recurring_token}/orders
  • Accept: application/vnd.klarna.checkout.recurring­-order-­accepted-­v1+json
  • Content-Type: application/vnd.klarna.checkout.recurring-­order­-v1+json
  • Body: …
  • Response
  • See examples below

HTTP Request

Set activate TRUE if the order should be auto activated. Do not send activate at all if order should not be auto activated. In this case an activation through the normal flow is needed.

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
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
POST /checkout/recurring/\{recurring_token\}/orders HTTP/1.1
Host: checkout.testdrive.klarna.com
Accept: application/vnd.klarna.checkout.recurring­-order-­accepted-­v1+json 
Authorization: Klarna o4qs59NZqPKm6IDr6E/GNA==
Content-­Type: application/vnd.klarna.checkout.recurring-­order­-v1+json

{
    "activate": true,
    "cart": {
        "items": [
            {
                "type": "physical",
                "reference": "123456789",
                "name": "Tomatoes (Spain)",
                "quantity": 2,
                "unit_price": 950,
                "discount_rate": 1000,
                "tax_rate": 2500
            },
            {
                "type": "physical",
                "reference": "987654321",
                "name": "Rotten Tomatoes",
                "quantity": 2,
                "unit_price": -100,
                "discount_rate": 0,
                "tax_rate": 0
            }
        ]
    },
    "billing_address": {
        "given_name": "Testperson-se",
        "family_name": "Approved",
        "street_address": "Stårgatan 1",
        "postal_code": "12345",
        "city": "Ankeborg",
        "country": "se",
        "email": "checkout@testdrive.klarna.com",
        "phone": "0765260000"
    },
    "shipping_address": {
        "given_name": "Testperson-se",
        "family_name": "Approved",
        "street_address": "Stårgatan 1",
        "postal_code": "12345",
        "city": "Ankeborg",
        "country": "se",
        "email": "checkout@testdrive.klarna.com",
        "phone": "0765260000"
    },
    "purchase_currency": "sek",
    "purchase_country": "se",
    "locale": "sv­-se",
    "merchant_reference": {
        "orderid1": "123",
        "orderid2": "345"
    },
    "merchant": {
        "id": "2"
    }
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

HTTP Response

Approved - Auto activate

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
HTTP/1.1 200 OK
Content­-Type: application/vnd.klarna.checkout.recurring­-order-­accepted­-v1+json

{
    "invoice": "{{_}}"
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

Approved - No auto activate

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
HTTP/1.1 200 OK
Content­-Type: application/vnd.klarna.checkout.recurring­-order-­accepted­-v1+json

{
    "reservation": "{{_}}"
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

Denied - Not accepted billing country

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
7
8
HTTP/1.1 403 Forbidden
Content-­Type: application/vnd.klarna.error­-v1+json

{
    "http_status_code": 403,
    "http_status_message": "Forbidden",
    "internal_message": "not_accepted_billing_country"
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

Denied - Service unavailable

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
7
HTTP/1.1 503 Service Unavailable
Content-­Type: application/vnd.klarna.error­-v1+json

{
    "http_status_code": 503,
    "http_status_message": "Service Unavailable"
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

Denied - Forbidden

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
7
8
HTTP/1.1 403 Forbidden
Content­-Type: application/vnd.klarna.error­-v1+json

{
    "http_status_code": 403,
    "http_status_message": "Forbidden",
    "internal_message": "forbidden_token"
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

Denied - Rejected invoice

Reasons:

  • address
  • rejected
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
7
8
9
HTTP/1.1 402 Payment Required
Content-­Type: application/vnd.klarna.checkout.recurring-­order­-rejected­-v1+json

{
    "reason": "{{<rejected_rc}}",
    "payment_method": {
        "type": "invoice"
    }
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

Denied - Credit card

Reasons:

  • temporary_failure
  • limit_exceeded
  • card_expired
  • permanent_failure
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 402 Payment Required
Content­-Type: application/vnd.klarna.checkout.recurring­-order­-rejected­-v1+json

{
    "reason": "{{<cc_failure}}",
    "payment_method": {
        "type": "credit_card",
        "credit_card_data": {
            "number": "**** **** **** 1234",
            "brand": "VISA",
            "expiry_year": 2014,
            "expiry_month": 10
        }
    }
}
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

Recurring Status

Fetch

Overview

HTTP Request

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
GET /checkout/recurring/\{recurring_token\} HTTP/1.1
Host: checkout.testdrive.klarna.com
Authorization: Klarna o4qs59NZqPKm6IDr6E/GNA==
Accept: application/vnd.klarna.checkout.recurring-status-v1+json
End of regional section
This section only applies to the regions:
Sweden, Norway, Finland

HTTP Response

End of regional section
This section only applies to the regions:
Sweden, Norway, Finland
1
2
3
4
5
6
7
8
9
10
11
12
13
14
HTTP/1.1 200 OK
Content-Type: application/vnd.klarna.checkout.recurring-status-v1+json

{
    "payment_method": {
        "type": "credit_card",
        "credit_card_data": {
            "number": "1111 22** **** 1234",
            "brand": "VISA",
            "expiry_year": 2017,
            "expiry_month": 8
        }
    }
}
End of regional section