Notes to type of payment

API-Requests - special notes / deviations

Overview of deviations

Clearingtype / Clearingsubtype

Summary

Klarna Checkout is a 3 step process.

Creating a new session via our server api

In the first step you need to setup a new checkout session. You can do so by sending a genericpamynet-request to our server api as listed below.

Please make sure to send the customer data within this request as they're needed to initiate a new session.

→ Genericpayment start_session

Optional update session

If the customer leaves the checkout page and comes back later, you can update the created session and change for example the address data.

→ Genericpayment update_session

Token-handling via Klarna widget

Part of the response is a client token. This token needs to be passed to the Klarna Widget. This Widget sends the client token together with the selected payment method (e.g. "Klarna Pay Later") to Klarna to get a authorization token.

→ Widget

Finalizing the checkout ((pre-)authorization) via our server api

In the last step, you need to send the authorization token received by Klarna widget as part of the (pre-)authorization request to our server api.

→ Preauthorization/Authorization

General integration information

There are a few things you need to take care of, when integrating Klarna checkout in your shop.

• You need to make sure, that the customer didn't accidently clicked on a Klarna payment method, because you will want to start the checkout process and directly send customer data to Klarna via "start_session" call. So please implement another step where the customer needs to confirm his payment method choice (for example: "By selecting this payment method we will send personal data to Klarna. Please confirm".
• After confirmation of the payment method, you want to start with the first calls to server api as described above and then display the Klarna Widget. This Klarna Widget needs defined parameters to only display the chosen payment method, even if the widget is capable of displaying more than one Klarna payment method. For example after selecting "Klarna Pay Later", the widget should look something like this:

Anchor
start_session start_session

Genericpayment start_session

start_session

BASE 64 String

APPROVED

ERROR

add_paydata[action]=start_session
aid=111111
amount=2222
api_version=1.00
birthday=1958101
city=Neuss
clearingtype=fnc
country=DE
currency=EUR
de[1]=for
ocean use only
email=klarna@approved.de
encoding=UTF-8
financingtype=KLS
firstname=Testperson-de
gender=m
id[1]=boat66
it[1]=goods
key=abcd12345698fffkfk
language=de
lastname=Approved
mid=11111
mode=test
no[1]=1
portalid=2011111
pr[1]=8540
request=genericpayment
salutation=Herr
street=Hellersbergstraße 14
telephonenumber=01522113356
va[1]=1900
zip=41460

status=OK
add_paydata[payment_method_category_name_3]=Slice it.
add_paydata[payment_method_category_name_2]=Pay later.
add_paydata[payment_method_category_name_1]=Direct debit
add_paydata[session_id]=123-2227-456-avc11-fefe456
add_paydata[payment_method_category_identifier_3]=pay_over_time
add_paydata[client_token]=W9uX2lkIiA6ICI3MGFjNGI3Ny0yMjI3LTdkNDEtY                      
add_paydata[payment_method_category_identifier_2]=pay_later                      add_paydata[payment_method_category_asset_url_standard_2]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_later/standard/pink.svg                        add_paydata[payment_method_category_asset_url_standard_1]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_now/standard/pink.svg                        add_paydata[payment_method_category_asset_url_standard_3]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/slice_it/standard/pink.svg                        add_paydata[payment_method_category_asset_url_descriptive_3]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/slice_it/descriptive/pink.svg                        add_paydata[payment_method_category_asset_url_descriptive_2]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_later/descriptive/pink.svg
add_paydata[payment_method_category_asset_url_descriptive_1]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_now/descriptive/pink.svg
add_paydata[payment_method_category_identifier_1]=direct_debit
workorderid=WX123456799

Anchor
update_session update_session

Genericpayment update_session

To update an order, you need to send a genericpayment-request with action=update. The call needs to provide the new list of items representing the complete shopping cart.

KIS (former KLV )

KIV (former KLS )

APPROVED

ERROR

Anchor
widget widget

Klarna Widget

the follwing integration steps are taken from Klarna documentation ( https://developers.klarna.com/documentation/klarna-payments/integration-guide/present-klarna-widget )

After creating a new session, you want to present the klarna widget to your customer. This widget allows you to present all 3 payment methods offered by Klarna to the customer or define what payment method should be presented to the customer. This is 

<script>
  window.klarnaAsyncCallback = function () {

    // This is where you start calling Klarna's JS SDK functions
    // 
    // Klarna.Payments.init({....})

  };
</script>
<script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>

Klarna.Payments.init({
  client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH'
})

<div id="klarna_container"></div>

Klarna.Payments.load({
    container: '#klarna-payments-container',
    payment_method_category: 'pay_later'
  }, function (res) {
    console.debug(res);
})

Anchor
authorization authorization

Preauthorization/Authorization

add_paydata[authorization_token]=aaa-bbbb-11111-2222-ccc
aid=12346
amount=8540
api_version=3.10
backurl=https://meine.test.url.de/Checkout/back
birthday=19600707
city=Neuss
clearingtype=fnc
country=DE
currency=EUR
de[1]=for ocean use only
email=klarna@approved.de
encoding=UTF-8
errorurl=https://meine.test.url.de/Checkout/error
financingtype=KLS
firstname=Testperson-de
gender=m
id[1]=boat66
it[1]=goods
key=e123dc456a
language=de
lastname=Approved
mid=12345
mode=test
narrative_text=0123456789012345678901234567890123456789
no[1]=1
portalid=2000123
pr[1]=8540
reference=R15595689952007
request=authorization
salutation=Herr
street=Hellersbergstraße 14
successurl=https://meine.test.url.de/Checkout/success
telephonenumber=01522113356
va[1]=1900
zip=41460

redirecturl=https://klarna-payments-eu.playground.klarna.com/v1/sessions/aaa-bbbb-11111-2222-ccc/redirect
status=REDIRECT
txid=30343747
userid=7890123

Capture

Debit / Refund

If you're using vouchers in your checkout, and want to partial refund items, you do have 2 options to do this:

• send a debit-request with the items using the original amount without any discounts and send a additional item as voucher, with an amount that sums up all discounts
  • example cart with auth
    • item 1; red car;  20 €
    • item 2; green truck; 30 €
    • item 3; voucher -10€ (-5€ discount on both items)
  • example cart with debit/refund
    • item 1; red car;  20 €
    • item 2; voucher -5€  (15€ for one item will be returned)
• send a debit-request with the items using an reduced amount, so that the whole discount is broken down on every item.
  • example cart with auth
    • item 1; red car;  20 €
    • item 2; green truck; 30 €
    • item 3; voucher -10€ (-5€ discount on both items)
  • example cart with debit/refund
    • item 1; red car;  15 €  (15€ for one item will be returned)