Prepare your checkout for Klarna

The first step is to go through how to display the payment options from Klarna in your checkout. It's critical that consumers recognise the Klarna brand, and that the information displayed is compliant with local market regulations. We'll guide you through it!


Collecting consumer information

Klarna just needs the customer's top of mind information such as billing details and in some cases, date of birth or social security number, to process an order. Most of this information you have already collected in your regular checkout process. Please make sure to check out which fields that apply in your market in our reserve amount API, so that you can collect them before placing the order with Klarna.


Payment method naming and presentation

Adding clear descriptions of the different payment methods allows consumers to understand the payment terms. We'll now go through how to collect and use information from Klarna when rendering your checkout

How does it work?

All you need to do is send our Payment Method Service API a few basic details, such as your merchant id, total cart value and locale. The API will then respond with a JSON object that contains all the information you need to render your checkout using our visual guidelines.


1. Create the digest

In order to authenticate against the service you would need to generate a digest. This consists of values from merchant_id, currency code and secret (in this order).

The digest is a sha256 encryption of the values in a colon separated string that is then base64 encoded, as the following pseudo code suggests:

base64encode(hex(sha256("[merchant_id]:[currency]:[shared_secret]")))

This digest should then be added to the Authorization header of the request:

Authorization: xmlrpc-4.2 xZWJjNjI5NmRjEwZThmMzE1MA==

2. Make the API call

Once you have collected all the required information go ahead and make the API call:

(Note that the URL for test and production/live differ. When accessing the live environment, you need to replace https://api-test.klarna.com/ with https://api.klarna.com/ in the example below)

curl "https://api-test.klarna.com/touchpoint/checkout/?merchant_id=0&currency=EUR&locale=de_DE&total_price=10000" \
    -H "Authorization: xmlrpc-4.2 xZWJjNjI5NmRlZjEwZThmMzE1MA==" \
    -H "Accept: application/vnd.klarna.touchpoint-checkout.payment-methods-v1+json"

The API call would produce the following HTTP request:

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

The API will then respond with all the information that you need to render the checkout.

{
  "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": "augusti"
                },
                "total_credit_purchase_cost": {
                    "value": "538,35"
                }
            },
            "title": "Flexible Laufzeit – Raten und Laufzeit selbst bestimmen",
            "extra_info": "...",
            "use_case": "..."
        }
    ]
}

 

Next, we will look at how to present this data in the best way in your checkout.


3. Render your checkout

As you have seen above, the response returned by the Payment Method Service is a JSON object containing a object for each available payment method. The concept with this object is that you are supposed to loop through it and present each containing object the same way, whatever type of payment it is. That said, it is important to point out that even though you do present it the same way, it will look a bit different due to the containing information.

Here is a visual layout example that we will go through in this section. A full reference guide for each market is available here

Grouping

The first element you need to take into consideration is the group->code value. This value tells you which group the payment option belongs to.

"group": {
    "title": "Flexible Laufzeit – Raten und Laufzeit selbst bestimmen",
    "code": "part_payment"
}

In theory you can present all option in a list, but from a user UX/UI perspective this will be both confusing and annoying. If there is a lot of data, it needs to be put into structure. Basically you should group each payment option into its respective group. Point A represent the grouping in the example below.

Klarna mainly work with two groups, invoice and part_payment, but a group called special_campaigns might also occur. You should however not focus on these variable values in general. These names might be vary. You should only focus on grouping the payment options based on the values, no matter what the names are.

 

Presenting the payment options:

The next step would be to present some options to the consumer. The name of the options you will present is represented by the payment options title. It will have different descriptions based on what option type it is.

"title": "Flexible Laufzeit – Raten und Laufzeit selbst bestimmen"

There is no way to sort these options in a given way. The payment options are returned in its correct order in the JSON object, and should be presented thereafter.

In the example below, point B represents the title:

Note that you should not focus on what options to present. You should present all options available in the group. The information returned by Klarna has taken into account the value etc, and only return acceptable options.

Detailed Payment Information:

For each payment option, there is a set of information that needs to be presented. This is important both from a legal perspective and a for transparency towards consumers. We want the consumer to understand what payment type they are selecting and what it implies. Detailed Payment Information consists of three parts that you must present:

  1. details    (D,E,F,G)
  2. use_case    (H)
  3. terms        (I)

Note that in the example you can see that the title is used on top of the payment details. This is done because of the structure of the example checkout. If you had presented the payment details directly below the option you selected, it would make less sense. Also note that all the information in the payment details should have the same weight to its presentation. That means that you should not make any text larger or bolder than the other.

Part 1 - Details

When presenting the details you shall not focus on what information that this object contains (D,E,F,G in example above). The actual content is not relevant. What you need to focus on is how you present it.

"details": {
    "interest_rate": {
        "label": "Jahreszins",
        "value": "18,07",
        "symbol": "%"
    },
    "monthly_invoice_fee": {
        "label": "Rechnungsgebühr",
        "value": "29",
        "symbol": "EUR"
    },
    "start_fee": {
        "label": "Bearbeitungsgebühren",
        "value": "0",
        "symbol": "EUR"
    }
},

The concept with the details is that you loop through the objects and present all its content in the same way: <label>  <value><symbol>. This way you ensure the dynamic capabilities of the PMS is kept. If there new information needs to be added, Klarna can just add it to the object. By handling the object this way it does not matter what kind of payment option this is (part payment, invoice etc) because the object only contains relevant information.

Part 2 - Use case

The use_case should be presented after the details. This is done to further enhance the understanding of what the customer is accepting.

For example:

Verfügungsrahmen ab 199,99 € (abhängig von der Höhe Ihrer Einkäufe), effektiver Jahreszins 18,07%* und Gesamtbetrag 218, 57€* (*bei Ausnutzung des vollen Verfügungsrahmens und Rückzahlung in 12 monatlichen Raten je 18,21 €).

 

Part 3 - Terms

The last part of the presentation is the terms. This section depends slightly on which payment methods you offer. Please check the full reference PDF guide for all payment methods available on this page to ensure you display and collect the details necessary in each case.

Terms and Conditions

Klarna’s terms and conditions for the method needs to be displayed in relation to the purchase. This text shall link to other pages as follows:

  • Weitere Informationen: is included in the response from Klarna under the variable terms.uri.
"terms": {
    "uri": "https://cdn.klarna.com/1.0/shared/content/legal/terms/131/de_de/account"
},

 

  • AGB mit Widerrufsbelehrung: https://cdn.klarna.com/1.0/shared/content/legal/de_de/account/terms.pdf
  • Standardinformationen für Verbraucherkredite: https://cdn.klarna.com/1.0/shared/content/legal/de_de/consumer_credit.pdf

Make sure this text is separated from the consent privacy policy text (I)

Consent privacy policy text

This text asks the customer to approve a transfer of their personal data to Klarna (3rd party) upon purchase so Klarna may do a credit check on them.

Mit der Übermittlung der für die Abwicklung der gewählten Klarna Zahlungsmethode und einer Identitäts– und Bonitätsprüfung erforderlichen Daten an Klarna bin ich einverstanden. Meine Einwilligung kann ich jederzeit mit Wirkung für die Zukunft widerrufen. Es gelten die AGB des Händlers.

This text shall link to other pages as follows:

  • Einwilligung: http://cdn.klarna.com/1.0/shared/content/legal/terms/YourEID/de_de/consent (replace YourEID with your merchant EID)
  • AGB des Händlers: Link to the store terms.

Please note:

  • This box cannot be pre checked.
  • The customer cannot place the order with Klarna without checking this box.

 


Presentation of order amount and buy button text

Lastly, a few words on the presentation of order amount and the buy button in relation to consumers paying with Klarna's fixed or flexible part payment options.

Order amount

When presenting the complete order amount in your checkout, make sure to use words and phrases which are not confusingly similar to the amount which is the total credit purchase price for a consumer choosing to use part payment. This means e.g. that "total amount" should not be used. Instead "order amount", "cash price" or similar are better suited, adapted to your local language.

Buy button

Similarly, the text on your buy button should also always clearly reflect that an order is being placed. Please note that there might be local regulatory requirements as to what it should state.


Great!

You are now ready for the next step, to prepare the back-end call to Klarna. Let's check out what you need to do before you create the order.