Notes to type of payment

Payment Type	Countries	Currency
Invoice	Danmark Germany Finland The Netherlands Norway Austria Sweden	Euro Danish crowns Norwegian crowns Swedish crowns
Installment	Danmark Germany Finland The Netherlands Norway Austria Sweden	Euro Danish crowns Norwegian crowns Swedish crowns

UI Text Box

type	note

B2B transactions are not supported.

API-Requests - special notes / deviations

Overview of deviations

UI Text Box

type	info

Klarna requires more specific customer data - depending on country of customer
Status "PENDING" has to be processed
- for API-response "PENDING"
- for TransactionStatus "pending"
Request "capture" has to use parameter "capturemode"
Request "debit" has to use parameter "settleaccount"
add_paydata and workorderid have to be used for update of shopping cart

Clearingtype / Clearingsubtype

clearingtype	fnc	Klarna payment types are handled as a financing payment
financingtype	KLS	Klarna "Slice It" (Installment)
financingtype	KLV	Klarna "Pay Later" (Invoice)

Summary

Klarna Checkout is divided in 3 steps.

UI Steps

UI Step

Create a new session

In the first step you need to setup a new checkout session. You can do so by sending a genericpaynent-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.

Optional

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

UI Step

Handle token

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.

UI Step

Finalize the checkout ((pre-)authorization)

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.

UI Text Box

type	note

The response contains a redirect-URL. You need to redirect the customer to this url, so that Klarna is able to securely handle data and optimize purchase flow. Klarna will automatically redirect the customer back again. The customer doens't need to take any action and will not notice this step in the background.

draw.io Diagram

border	true
viewerToolbar	true

fitWindow	false
diagramName	klarna_checkout
simpleViewer	false
width
diagramWidth	1401
revision	3

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 oyu need to take care of, when itnegrating Klarna checkout in your shop.

You need to make sure, that the customer didnd't accidently clicked on a Klarna payment method, because you will want to start the checkout preocess 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.
After confirmation of the payment method, you want to start witht he 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 exmpla,e after selecting Klarna Pay Later, the widget should something like this:
Image Added

Anchor
start_session
start_session
Genericpayment start_session

Request "generic start session"

API parameter

Required

Format

Comments

add_paydata[action]

+

Default

Fixed value "start_session"

add_paydata[merchant_data]

-

BASE 64 String

"EMD" - Extra Merchant Data - means that integration with any such package depends on (i) merchant’s offering and (ii)
merchant’s technical possibilities. It is not to be interpreted in such a way that EMD is not required at all.

firstname

+

AN..50

First name

lastname

+

AN2..50

Surname

street

+

AN1..50

Street number and name

(required: at least one character)

zip

+

AN2..10

Postcode, format [a-zA-Z0-9_.-/ ]{2,10}

city

+

AN2..50

City

country

+

Default

Country (ISO 3166)

addressaddition

+

AN1..50

Address line 2 (e.g. "7th floor", "c/o Maier")

gender

o

Default

f=female, m=male

ip

+

AN..39

Customer's IP-V4-address (123.123.123.123) or IP
V6-address

email

+

AN..254

Email address

telephonenumber

+

AN..30

Telephone number

birthday

o

N8

Date of birth (YYYYMMDD)

shipping_firstname

-

AN..50

First name

shipping_lastname

-

AN..50

Surname

shipping_company

-

AN2..50

Company

shipping_street

-

AN1..50

Street number and name (required: at least one character)

shipping_zip

-

AN2..10

Postcode, format [a-zA-Z0-9_.-/]{2,10}

shipping_city

-

AN2..50

City

shipping_country

-

Default

Country (ISO 3166)

add_paydata[last_four_ssn]

-

Last four digits for customer social security number.

add_paydata[organization_entity_type]

-

Only relevant for B2B transactions.

personalid

o

AN..32

Person specific numbers or characters

it[n]

+

Default

For KLV / KLS: Item type

goods	Goods
shipment	Shipping charges
handling	Handling fee
voucher	Voucher / discount

id[n]

+

AN..32

Product number, order number, etc.
Permitted symbols:
0-9 a-z A-Z ()[]{} +-_#/:
[n] starting with [1]; serially numbered; max [400]

pr[n]

+

N..10

Unit gross price in cent, max. 19 999 999 99
[n] starting with [1]; serially numbered; max [400]

no[n]

+

N..6

Quantity
[n] starting with [1]; serially numbered; max [400]

de[n]

+

AN..50

Description
[n] starting with [1]; serially numbered; max [400]

va[n]

+

N..4

VAT rate (% or bp) of gross price
Mandatory for payment type KLV, KLS
[n] starting with [1]; serially numbered; max [400]

add_paydata[klsid]

+

Mandatory for Klarna Installment (KLS): Campaign code

API parameter	Required	Comments
Response "genericpayment - start_session"
add_paydata[session_id]	+	Identifier for the started session at Klarna
add_paydata[client_token]	+	Client token to authorize the session for payment via Klarna Widget
add_paydata[authorized_payment_method]	+	Name of payment that got authorized for customer payment. (You will only receive the parameters according to the payment method you selected via clearingtype and financingtype)
add_paydata[payment_method_category_name]	+	Name of Klarna payment category
add_paydata[payment_method_category_identifier]	+	Identifier for Klarna payment category
add_paydata[payment_method_category_asset_url_descriptive]	+	URL of Klarna payment category assets for descriptive design (payment method identified by small icon and test on badge)
add_paydata[payment_method_category_asset_url_standard]	+	URL of Klarna payment category assets for standard design (payment method only identified by small icon on badge)
status	+
APPROVED
workorderid	+
ERROR
errorcode	+
errormessage	+
customermessage	+

Code Block

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

Code Block

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.

UI Text Box

type	note

An update is only possible as long as the preauthorization is not captured completly.
Don’t send the difference/changes, instead you need to send the complete new item list
The amount can’t be higher as the amount of the preauthorization. A lower amount is allowed.

Request "genericpayment - update"

API parameter

Required

Comments

add_paydata[action]

+

Fixed value "update"

add_paydata[reservation_txid]

+

Referencing the reservation (received from authorization.response -> add_paydata[reservation_txid])

workorderid

+

Referencing the reservation (received from authorization.response -> add_paydata[workorderid])

country

+

Default

Country (ISO 3166)

amount

+

N..10

Total gross amount (in smallest currency unit! e.g.
cent, max. 19 999 999 99)

currency

+

Default

Currency (ISO 4217)

financingtype

+

Fixed value "KLV/KLS"

it[n]

+

Default

For KLV / KLS: Item type

goods	Goods
shipment	Shipping charges
handling	Handling fee
voucher	Voucher / discount

id[n]

+

AN..32

Product number, order number, etc.
Permitted symbols:
0-9 a-z A-Z ()[]{} +-_#/:
[n] starting with [1]; serially numbered; max [400]

pr[n]

+

N..10

Unit gross price in cent, max. 19 999 999 99
[n] starting with [1]; serially numbered; max [400]

no[n]

+

N..6

Quantity
[n] starting with [1]; serially numbered; max [400]

de[n]

+

AN..50

Description
[n] starting with [1]; serially numbered; max [400]

va[n]

+

N..4

VAT rate (% or bp) of gross price
Mandatory for payment type KLV, KLS
[n] starting with [1]; serially numbered; max [400]

API parameter	Required	Comments
Response "genericpayment - update"
status	+	APPROVED / ERROR
APPROVED
workorderid	+
ERROR
errorcode	+
errormessage	+
customermessage	+

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

UI Steps

UI Step

Add SDK to your page (insert in body)

Code Block

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

UI Step

Initialize SDK and place a container on your page

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

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

UI Step

Load Klarna Widget

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

UI Step

Receive Response from load call

Klarna’s widget uses the show_form:true/false field as a response flag to load and to authorize calls in the Javascript SDK.

Positive Response

If show_form: true, and there are no errors in the object returned, Klarna renders the payment options available to the customer in the widget.

Adjust and try again

If show_form: true, but an error is returned as well, then something is wrong and the consumer needs to take action before moving forward. Klarna will inform the consumer about the details of the error in the widget. Optionally, you can interpret the invalid fields in the error message and take appropriate actions on your checkout page. See the JavaScript SDK reference page for further information.

Negative Response

If show_form: false, the payment method chosen by the customer will not be offered for this order based on Klarna’s evaluation. A message is displayed to the consumer in the Widget.

When Klarna returns a show_form: false, your store cannot offer the selected payment method to this customer. You need to present other payment methods to the customer.

Anchor
authorization
authorization
Preauthorization/Authorization

Request "preauthorization / authorization"

API parameter

Required

Comments

firstname

+

AN1..50

First name

lastname

+

AN2..50

Surname

company

-

AN..50

If filled, the transaction is marked as B2B.

street

+

AN1..50

Street number and name

zip

+

AN2..10

Postcode, format [a-zA-Z0-9_.-/]{2,10}

city

+

AN2..50

City

country

+

Default

Country (ISO 3166)

addressaddition

+

AN1..50

Address line 2 (e.g. "7th floor", "c/o Maier")

gender

o

Default

f=female, m=male

ip

+

AN..39

Customer's IP-V4-address (123.123.123.123) or IP
V6-address

email

+

AN..254

Email address

telephonenumber

+

AN..30

Telephone number

birthday

o

N8

Date of birth (YYYYMMDD)

Mandatory for Germany, Netherlands and Austria

shipping_firstname

-

AN..50

First name

shipping_lastname

-

AN..50

Surname

shipping_company

-

AN2..50

Company

shipping_street

-

AN1..50

Street number and name (required: at least one character)

shipping_zip

-

AN2..10

Postcode, format [a-zA-Z0-9_.-/]{2,10}

shipping_city

-

AN2..50

City

shipping_country

-

Default

Country (ISO 3166)

personalid

o

AN..32

Mandatory for Sweden, Finland, Denmark and Norway

it[n]

+

Default

For KLV / KLS: Item type

goods	Goods
shipment	Shipping charges
handling	Handling fee
voucher	Voucher / discount

id[n]

+

AN..32

Product number, order number, etc.
Permitted symbols:
0-9 a-z A-Z ()[]{} +-_#/:
[n] starting with [1]; serially numbered; max [400]

pr[n]

+

N..10

Unit gross price in cent, max. 19 999 999 99
[n] starting with [1]; serially numbered; max [400]

no[n]

+

N..6

Quantity
[n] starting with [1]; serially numbered; max [400]

de[n]

+

AN..255

Description
[n] starting with [1]; serially numbered; max [400]

va[n]

+

N..4

VAT rate (% or bp) of gross price
Mandatory for payment type KLV, KLS
[n] starting with [1]; serially numbered; max [400]

add_paydata[klsid]

o

Mandatory for Klarna Installment (KLS): Campaign code

Code Block

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

API parameter	Required	Comments
Response "preauthorization / authorization"
add_paydata[workorderid]	+	Klarna Invoice: Workorder ID, used for update calls (cart updates)
add_paydata[reservation_txid]	+	Klarna Invoice: Reservation ID, used for update calls (cart updates)

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

Capture

API parameter	Required	Comments
Request "capture"
capturemode	+	Parameter capturemode is mandatory to indicate whether this capture will be the last one. (Default: completed)
settleaccount	+	Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes)

API parameter	Required	Comments
Response "capture"
clearing_instructionnote	o	A URL pointing to a PDF of the invoice. (If invoice by post or by e-mail isn’t activated.) The URL is valid for 30 days. This feature has to be requested.

Debit / Refund

API parameter	Required	Comments
Request "debit"
settleaccount	+	Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes)

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)

Table of Contents

outline	true
indent	2em

Page tree

Page History

Versions Compared

Old Version 50

New Version 51

Key

Notes to type of payment

API-Requests - special notes / deviations

Overview of deviations

Clearingtype / Clearingsubtype

Summary

Create a new session

Optional

Handle token

Finalize the checkout ((pre-)authorization)

Creating a new session via our server api

Optional update session

Token-handling via Klarna Widget

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

General integration information

Anchorstart_sessionstart_sessionGenericpayment start_session

Request "generic start session"

Response "genericpayment - start_session"

Anchorupdate_sessionupdate_sessionGenericpayment update_session

Request "genericpayment - update"

Response "genericpayment - update"

AnchorwidgetwidgetKlarna Widget

Positive Response

Adjust and try again

Negative Response

AnchorauthorizationauthorizationPreauthorization/Authorization

Request "preauthorization / authorization"

Response "preauthorization / authorization"

Capture

Request "capture"

Response "capture"

Debit / Refund

Request "debit"

Anchor
start_session
start_session
Genericpayment start_session

Anchor
update_session
update_session
Genericpayment update_session

Anchor
widget
widget
Klarna Widget

Anchor
authorization
authorization
Preauthorization/Authorization