Introduction

The Klarna Dynamic store assets API is the interface for all our widgets and services, such as the Part Payment Widget, KPM checkout service, etc.

This reference guide will allow you to dive into the details of our API for even more control of your integration.

Live environment access information

To use the Dynamic store assets API, you need live API credentials. Please contact your integration sales representative.

Host: api.klarna.com
port: 443

Digest

A digest is a cryptographic hash function that takes a block of data and returns a fixed-size bit string. The digest is used to verify the integrity of the call as well as to identify the caller, and sent in as a base64 encoded string.

Note: the string is formatted to hexadecimal before encoding.  

Supported hashing algorithms are, in descending order of recommendation:

  • SHA-256

Methods

Checkout Page

To show available payment methods on a checkout page using invoice and part payment.

Digest

Consists of the xmlrpc client version followed by values from merchant_id, currency code and secret (in this order) separated with a colon without the square brackets. The format for the constructing the correct header is: 

Authorization: {XMLRPC-VERSION} {DIGEST}

The complete header would look like this:

Authorization: xmlrpc-4.2 xZWJjNjI5NmRlZjEwZThmMzE1MA==

Only a proprietary Klarna authentication scheme is supported. The table below, shows what to replace the placeholder values with.

{XMLRPC-VERSION}xmlrpc-4.2
{DIGEST}base64encode(hex(sha256("[merchant_id]:[currency]:[shared_secret]")))

The DIGEST formula is broken down to the following components.

merchant_idThe unique number that identifies your e-store
currency_codeThe three letter uppercase currency of your store, based on ISO 4217. Currencies supported at this time are: EUR, NOK, SEK
shared_secretThis is the shared secret key assigned to your merchant_id by Klarna

Request

After the header has been created, an HTTP GET request must be made and sent along with the header. This is what the HTTP GET request looks like:

https://api.klarna.com/touchpoint/checkout/?merchant_id=[merchant_id]&currency=[currency]&locale=[locale]&total_price=[total_price]

* Required

VariableTypeDescription
merchant_id *intThe unique number that identifies your e-store
total_price *intTotal price of the purchase, in cents, e.g. 500.00 kr == 50000
currency *stringCurrency used for the purchase. Currency codes are defined in ISO 4217.
locale *stringLocale used when displaying texts. It is a ISO 639 language code and a ISO 3166-1 alpha-2 country code, e.g. sv_se

Example

GET /touchpoint/checkout/?merchant_id=0&currency=EUR&locale=de_de&total_price=10000 HTTP/1.1
Host: api.klarna.com
Accept: application/vnd.klarna.touchpoint-checkout.payment-methods-v1+json
Authorization:  xmlrpc-4.2 xZWJjNjI5NmRjEwZThmMzE1MA==
User-Agent: curl/7.35.0

Response

The response will be a JSON envelope structure with a list of payment methods. And a payment method will have the following fields:

FieldTypeDescription
pclass_idnumberThe pclass id number. This is to be used in the reserveAmount call.
namestringName of the payment option in English.
terms.uristringAbsolute URL to the terms for this payment method
logo.uristringAbsolute URL to the logo used for this payment method
titlestringTitle to display for payment option
extra_infostringDetailed information about payment option
group.codestringPayment option group
use_casestringCalculation example of payment option
detailsobjectBreakdown of fees and various information to be used by merchant as he see fit
details.interest_rate.valuestringInterest rate for payment option
details.monthly_pay.valuestringCalculated monthly payment. Value is displayed in localized format depending on the locale that is sent in the parameters.
details.months.valuenumberNumber of installments for payment option.
details.month.valuestringThe localised name of the month
details.annual_percentage_rate.valuestringCalculated annual percentage rate.
details.montly_invoice_fee.valuestringMonthly administrator invoice fee
details.total_credit_purchase_price.valuestringThe total amount that is payable for this purchase, including starting fee, administrative fees and interest rates
details.start_fee.valuestringThe start fee of the instalment

Example

HTTP/1.1 200 OK
Connection: close
Content-Length: 1002
Content-Type: application/vnd.klarna.touchpoint-checkout.payment-methods-v1+json; charset=utf-8
Date: Thu, 17 Jul 2014 14:29:00 GMT
ETag: W/"612-3862573905"
Server: nginx

{
  "payment_methods": [
        {
            "pclass_id": 100,
            "name": "Account",
            "logo": {
                "uri": "https://cdn.klarna.com/1.0/shared/image/generic/logo/de_de/basic/blue-black.png"
            },
            "terms": {
                "uri": "https://cdn.klarna.com/1.0/shared/content/legal/terms/0/de_de/account"
            },
            "group": {
                "code": "part_payment"
            },
            "details": {
                "annual_percentage_rate": {
                    "value": "11,95"
                },
                "interest_rate": {
                    "value": "14,79"
                },
                "monthly_invoice_fee": {
                    "value": "0,45"
                },
                "setup_fee": {
                    "value": "0"
                },
                "monthly_pay": {
                    "value": "44,86"
                },
                "months": {
                    "value": 3
                },
                "month": {
                    "value": "august"
                },
                "total_credit_purchase_cost": {
                    "value": "1145"
                }
            },
            "title": "Flexible Laufzeit – Raten und Laufzeit selbst bestimmen",
            "extra_info": "...",
            "use_case": "..."
        }
    ]
}

Errors

If for whatever reason the HTTP request results in an error, the JSON output will indicate the error.

Example

HTTP/1.1 401 Unauthorized
Server: nginx
Date: Fri, 18 Jul 2014 12:57:16 GMT
Content-Type: application/vnd.klarna.error-v1+json; charset=utf-8
Connection: close
Content-Length: 212
ETag: W/"bd-1819756749"

{
    "http_status_code": 401,
    "http_status_message": "Unauthorized",
    "internal_code": "12 dry toads kissed jovially",
    "internal_message": "Failed to authenticate",
    "public_code": "unauthorized"
}