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 (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
idstringRUnique identifier of the Klarna Checkout Order
purchase_countrystringMCountry in which the purchase is done (ISO-3166-alpha2)
purchase_currencystringMCurrency in which the purchase is done (ISO-4217)
localestringMLocale indicative for language & other location-specific details (RFC1766)
statusstringR*Status. `checkout_incomplete` by default, alternatively `checkout_complete`, `created`
referencestringREnd-consumer friendly reference
reservationstringRReservation number to be used in the XML-RPC API
recurringbooleanOOnly in Sweden, Norway and Finland: Indicates whether this purchase is a recurring order
recurring_tokenstringRToken to be used when creating recurring orders
merchant_referencemerchant reference objectO*Merchant references
billing_addressaddress objectRThe billing address
shipping_addressaddress objectOThe shipping address
cartcart objectMThe cart
customercustomer objectOInformation about the liable customer of the order.
guigui objectOThe gui object
merchantmerchant objectMMerchant related information.
attachmentattachment objectOAdditional purchase information required for some industries.
external_payment_methodsarray of external payment method objectsOExternal payment methods
external_checkoutsarray of external checkout objectsOExternal checkout providers
optionsoptions objectOOptions for this purchase, read more here.
started_atstringRTimestamp of when the Checkout started (ISO-8601)
completed_atstringRTimestamp of when the Checkout was completed (ISO-8601)
created_atstringRTimestamp of when the Order was created (ISO-8601)
last_modified_atstringRTimestamp of when the Checkout was last modified (ISO-8601)
expires_atstringRTimestamp of when the Checkout will expire (ISO-8601)

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

merchant reference object properties

VariableTypeDescription
orderid1stringOUsed for storing merchant's internal order number or other reference.
orderid2stringOUsed for storing merchant's internal order number or other reference.

address object properties

VariableTypeDescription
given_namestringRFirst name
family_namestringRLast name
care_ofstringRc/o
street_addressstringROnly in Sweden, Norway and Finland: Street address (street name, street number, street extension)
street_namestringROnly in Germany: Street name
street_numberstringROnly in Germany: Street number
postal_codestringRPostal code
citystringRCity
countrystringRCountry (ISO-3166 alpha)
emailstringRE-mail address
phonestringRPhone number
titlestringROnly in Germany: The customer's title, possible values are "Herr" and "Frau"

cart object properties

VariableTypeDescription
total_price_excluding_taxintegerRTotal price (excluding tax) in cents
total_tax_amountintegerRTotal tax amount in cents
total_price_including_taxintegerRTotal price (including tax) in cents
itemsarray of cart item objectsMList of cart items

cart item object properties

VariableTypeDescription
typestringOType. `physical` by default, alternatively `discount`, `shipping_fee`
eanstringOThe item's International Article Number. Please note this property is currently not returned when fetching the full order resource.
referencestringMReference, usually the article number
namestringMName, usually a short description
uristringOItem product page URI. Please note this property is currently not returned when fetching the full order resource.
image_uristringOItem image URI. Please note this property is currently not returned when fetching the full order resource.
quantityintegerMQuantity
unit_priceintegerMUnit price in cents, including tax
total_price_excluding_taxintegerRTotal price (excluding tax) in cents
total_tax_amountintegerRTotal tax amount, in cents
total_price_including_taxintegerRTotal price (including tax) in cents
discount_rateintegerOPercentage of discount, multiplied by 100 and provided as an integer. i.e. 9.57% should be sent as 957
tax_rateintegerMPercentage of tax rate, multiplied by 100 and provided as an integer. i.e. 13.57% should be sent as 1357

customer object properties

VariableTypeDescription
date_of_birthstringOIf provided by customer, or retrieved from national ID. The customer's birthdate (YYYY-MM-DD)
genderstringORetrieved from national ID or billing_address.title in Germany. 'female' or 'male'
typestringRType. Currently the only supported value is 'person'

gui object properties

VariableTypeDescription
layoutstringOLayout. `desktop` by default, alternatively `mobile`
optionsarray of stringsOAn array of options to define the checkout behaviour. Supported options `disable_autofocus`.
snippetstringRHTML snippet

merchant object properties

VariableTypeDescription
idstringMUnique identifier (EID)
terms_uristringMURI of your terms and conditions
checkout_uristringMURI of your checkout page
confirmation_uristringMURI of your confirmation page
push_uristringMURI of your push-notification page
validation_uristringOURI of your validation page, see validate a checkout order.
back_to_store_uristringOURI of your store page. Used on the settlement page.

attachment object properties

VariableTypeDescription
bodystringMThe attachment body. 
content_typestringMThe content type of the body property.

A list of available attachment types can be found here.

external payment method object properties

VariableTypeDescription
namestringMPayment method name
redirect_uristringMURI of external payment method page
image_uristringOURI of external payment method image (https://)
feeintegerOFee in cents, including tax
descriptionstringO500 character limit. Links can be set with the Markdown syntax [Text](URL)

external checkout object properties

VariableTypeDescription
namestringMCheckout name
redirect_uristringMURI of external payment method page
image_uristringOURI of external payment method image (https://)
feeintegerOFee in cents, including tax

options object properties

VariableTypeDescription
color_buttonstringOOnly hexadecimal values are allowed.
color_button_textstringOOnly hexadecimal values are allowed.
color_checkboxstringOOnly hexadecimal values are allowed.
color_checkbox_checkmarkstringOOnly hexadecimal values are allowed.
color_headerstringOOnly hexadecimal values are allowed.
color_linkstringOOnly hexadecimal values are allowed.
shipping_detailsstringOShipping information displayed on the confirmation page. Maximum 70 characters.
phone_mandatorybooleanOMaking the phone field mandatory (Only available in Germany and Austria)
allow_separate_shipping_addressbooleanOTo allow separate shipping addresses  (Only available in Germany and Austria)
packstation_enabledbooleanOEnable packstation  (Only available in Germany)
date_of_birth_mandatorybooleanOMaking the date of birth mandatory

Errors

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

Status codeDescription
200OKThe request was successful.
201CreatedThe request was successful and created a new resource at the URI described by the `Content-Location` response header
400Bad RequestThe request did not pass validation due to syntax or semantic errors. Error message should indicate the error.
401UnauthorizedAuthentication failed due to an invalid or missing `Authentication` request header.
403ForbiddenThe server refused to fulfil it.
404Not FoundThere is no resource matching the request URI.
405Method Not AllowedThe resource did not expected the request method.
406Not AcceptableThe server cannot fulfil the `Accept` request header.
415Media Type Not SupportedThe 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
SwedenSwedishSESEKsv-se
FinlandFinnishFIEURfi-fi
FinlandSwedishFIEURsv-fi
NorwayNorwegianNONOKnb-no
 
GermanyGermanDEEURde-de
AustriaGermanATEURde-at
 

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.

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.uri}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.uri}"
    }
}

HTTP Response

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

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

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.uri}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.uri}"
    }
}

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

HTTP Request

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.uri}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.uri}"
    }
}

HTTP Response

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.uri}",
        "push_uri": "https://example.com/push.php?sid=123&klarna_order={checkout.order.uri}"
    }
}

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

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"
    }
}

HTTP Response

Approved - Auto activate

HTTP/1.1 200 OK
Content­-Type: application/vnd.klarna.checkout.recurring­-order-­accepted­-v1+json

{
    "invoice": "{{_}}"
}

Approved - No auto activate

HTTP/1.1 200 OK
Content­-Type: application/vnd.klarna.checkout.recurring­-order-­accepted­-v1+json

{
    "reservation": "{{_}}"
}

Denied - Not accepted billing country

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"
}

Denied - Service unavailable

HTTP/1.1 503 Service Unavailable
Content-­Type: application/vnd.klarna.error­-v1+json

{
    "http_status_code": 503,
    "http_status_message": "Service Unavailable"
}

Denied - Forbidden

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"
}

Denied - Rejected invoice

Reasons:

  • address
  • rejected
HTTP/1.1 402 Payment Required
Content-­Type: application/vnd.klarna.checkout.recurring-­order­-rejected­-v1+json

{
    "reason": "{{<rejected_rc}}",
    "payment_method": {
        "type": "invoice"
    }
}

Denied - Credit card

Reasons:

  • temporary_failure
  • limit_exceeded
  • card_expired
  • permanent_failure
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
        }
    }
}

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

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

HTTP Response

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
         }
    }
}