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

Name	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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.

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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

Variable	Type		Description
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 code		Description
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.

Country	Language	purchase_country	purchase_currency	locale
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

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

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

Description: Fetch a recurring status resource
Request
Method: GET
URI: https://checkout.testdrive.klarna.com/checkout/recurring/{recurring_token}
Accept: application/vnd.klarna.checkout.recurring-status-v1+json
Content-Type: -
Body: -
Response
A representation of the recurring status

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