Notes to type of payment

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

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"
- API version
- Notify-Version
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 Installment
financingtype	KLV	Klarna 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.

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

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): Campaigsn 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.
add_paydata[payment_method_category_name_n]	+	"n" starts at 1 and is then incremented if necessary.
add_paydata[payment_method_category_identifier_n]	+	"n" starts at 1 and is then incremented if necessary.
add_paydata[payment_method_category_asset_url_descriptive_n]	+	"n" starts at 1 and is then incremented if necessary.
add_paydata[payment_method_category_asset_url_standard_n]	+	"n" starts at 1 and is then incremented if necessary.
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	+

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)

Table of Contents

outline	true
indent	2em

Page tree

Page History

Versions Compared

Old Version 41

New Version 42

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

Anchorstart_sessionstart_session

Genericpayment start_session

Request "generic start session"

Response "genericpayment - start_session"

Anchorupdate_sessionupdate_session

Genericpayment update_session

Request "genericpayment - update"

Response "genericpayment - update"

Anchorwidgetwidget

Klarna Widget

Positive Response

Adjust and try again

Negative Response

Anchorauthorizationauthorization

Preauthorization/Authorization

Request "preauthorization / authorization"

Response "preauthorization / authorization"

Capture

Request "capture"

Response "capture"

Debit / Refund

Request "debit"

Anchor
start_session
start_session

Anchor
update_session
update_session

Anchor
widget
widget

Anchor
authorization
authorization