Notes on This Type of Payment

Payment Type

Countries

Currency

Invoice ("Pay later")

Austria
Danmark
Finland
Germany
The Netherlands
Norway
Sweden

Euro
Danish crowns
```
Norwegian crowns
```
```
Swedish crowns
```

Installment ("Slice it")

Direct Debit ("Pay now")

UI Text Box

type	note

B2B transactions are currently only supported in Finland, Germany, Norway and Sweden.

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" implementation of API-version 3.11 or higher is required
- for TransactionStatus "pending" implementation of notify-version 7.6 or higher is required
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	financingtype
fnc	KIS	Klarna "Slice It" (Installment)
fnc	KIV	Klarna "Pay Later" (Invoice)
fnc	KDD	Klarna "Pay Now" (Direct Debit)

Summary

Klarna Checkout is a 3 step process.

UI Steps

UI Step

Create a New Session

The first step is to setup a new checkout session 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 you need to take care of, when integrating Klarna checkout in your shop.

You need to ensure, that the customer only triggers the "start_session" call by choosing Klarna as a payment method intentionally. As personal data will be sent to Klarna within said, he has to actively confirm this (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
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
start_session
start_session
Genericpayment start_session

Request "Generic Start Session"

API parameter

Required

Comments

add_paydata[action]

+

identifies the request as one to start a new session

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Fixed Value

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

start_session

add_paydata[merchant_data]

-

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

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

BASE 64 String

amount

+

Excerpt Include

	amount - definition
	amount - definition
nopanel	true

currency

+

Excerpt Include

	currency - definition
	currency - definition
nopanel	true

firstname

+

Excerpt Include

	firstname - definition
	firstname - definition
nopanel	true

lastname

+

Excerpt Include

	lastname - definition
	lastname - definition
nopanel	true

title

-

Excerpt Include

	title - definition
	title - definition
nopanel	true

street

+

Excerpt Include

	street - definition
	street - definition
nopanel	true

zip

+

Excerpt Include

	zip - definition
	zip - definition
nopanel	true

city

+

Excerpt Include

	city - definition
	city - definition
nopanel	true

country

+

Excerpt Include

	country - definition
	country - definition
nopanel	true

state

-

Excerpt Include

	state - definition
	state - definition
nopanel	true

addressaddition

+

Excerpt Include

	addressaddition - definition
	addressaddition - definition
nopanel	true

gender

o

Excerpt Include

	gender - definition
	gender - definition
nopanel	true

ip

+

Excerpt Include

	ip - definition
	ip - definition
nopanel	true

email

+

Excerpt Include

	email - definition
	email - definition
nopanel	true

telephonenumber

-

Excerpt Include

	telephonenumber - definition
	telephonenumber - definition
nopanel	true

birthday

o

Excerpt Include

	birthday - definition
	birthday - definition
nopanel	true

mandatory for Austria, Germany, Switzerland and the Netherlands.

language

+

Excerpt Include

	language - definition
	language - definition
nopanel	true

shipping_firstname

-

Excerpt Include

	shipping_firstname - definition
	shipping_firstname - definition
nopanel	true

shipping_lastname

-

Excerpt Include

	shipping_lastname - definition
	shipping_lastname - definition
nopanel	true

add_paydata[shipping_title]

-

Title recipient within the delivery address

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

CHAR(1..50)

shipping_company

-

Excerpt Include

	shipping_company - definition
	shipping_company - definition
nopanel	true

shipping_street

-

Excerpt Include

	shipping_street - definition
	shipping_street - definition
nopanel	true

shipping_zip

-

Excerpt Include

	shipping_zip - definition
	shipping_zip - definition
nopanel	true

shipping_city

-

Excerpt Include

	shipping_city - definition
	shipping_city - definition
nopanel	true

shipping_country

-

Excerpt Include

	shipping_country - definition
	shipping_country - definition
nopanel	true

shipping_state

-

Excerpt Include

	shipping_state - definition
	shipping_state - definition
nopanel	true

add_paydata[shipping_telephonenumber]

-

telephone number of the recipient or a contact at the delivery address

Section

Layout box

cssClass	payoneFormat
floating	left

Format

Layout box

cssClass	payoneFormatValue
floating	left

CHAR(1..30)

add_paydata[shipping_email]

o

email-address of the recipient or a contact at the delivery address

Section

Layout box

cssClass	payoneFormat
floating	left

Format

Layout box

cssClass	payoneFormatValue
floating	left

CHAR(5..254)

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Symbols

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

RFC 5322

This parameter is required if a shipping adress is given.

add_paydata[last_four_ssn]

-

Last four digits for customer social security number.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

NUMERIC(4)

add_paydata[organization_entity_type]

-

Only relevant for B2B transactions.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

LIMITED_COMPANY
PUBLIC_LIMITED_COMPANY
ENTREPRENEURIAL_COMPANY
LIMITED_PARTNERSHIP_LIMITED_COMPANY
LIMITED_PARTNERSHIP
GENERAL_PARTNERSHIP
REGISTERED_SOLE_TRADER
SOLE_TRADER
CIVIL_LAW_PARTNERSHIP
PUBLIC_INSTITUTION
OTHER

add_paydata[organization_registry_id]

-

will be given to Klarna as "vat_id"

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

CHAR(1..50)

personalid

o

Excerpt Include

	personalid - definition
	personalid - definition
nopanel	true

Mandatory for Denmark, Finland, Norway and Sweden

it[n]

+

Klarna item type

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

goods      : Goods

shipment   : Shipping charges

handling   : Handling fee

voucher    : Voucher / discount

id[n]

+

Excerpt Include

	id[n] - definition
	id[n] - definition
nopanel	true

pr[n]

+

Excerpt Include

	pr[n] - definition
	pr[n] - definition
nopanel	true

no[n]

+

Excerpt Include

	no[n] - definition
	no[n] - definition
nopanel	true

de[n]

+

Excerpt Include

	de[n] - definition
	de[n] - definition
nopanel	true

va[n]

+

Excerpt Include

	va[n] - definition
	va[n] - definition
nopanel	true

add_paydata[klsid]

+

Mandatory for Klarna Installment (KIS): Campaign code

Response "Genericpayment - start_session"

API parameter

Required

Comments

add_paydata[session_id]

+

Identifier for the started session at Klarna

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Sample

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

068df369-13a7-4d47-a564-62f8408bb760

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

Payment Method Category to show on the Payment Page.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

DIRECT_DEBIT
DIRECT_BANK_TRANSFER
PAY_NOW
PAY_LATER
PAY_OVER_TIME

currently only pay_later and pay_over_time are supported

add_paydata[payment_method_category_identifier]

+

Identifier for Klarna payment category

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

pay_later

direct_debit

pay_over_time

direct_debit is currently not supported

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)

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Sample

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg

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)

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Sample

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg

status

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

APPROVED

ERROR

APPROVED

workorderid

+

Excerpt Include

	workorderid - definition
	workorderid - definition
nopanel	true

ERROR

errorcode

+

Excerpt Include

	errorcode - definition
	errorcode - definition
nopanel	true

errormessage

+

Excerpt Include

	errormessage - definition
	errormessage - definition
nopanel	true

customermessage

+

Excerpt Include

	customermessage - definition
	customermessage - definition
nopanel	true

Code Block

title	Genericpayment start_session - Example Request

mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=genericpayment
encoding=UTF-8
aid=12345 (your aid)
clearingtype=fnc
financingtype=KIS
amount=3000
currency=EUR
lastname=Approved
firstname=Testperson-de
salutation=Herr
country=DE
language=de
gender=m
add_paydata[action]=start_session
birthday=19600707
street=Hellersbergstraße 14
city=Musterstadt
zip=12345
email=youremail@email.com
telephonenumber=01512345678
de[1]=for the feet
id[1]=socks1
it[1]=goods
no[1]=1
pr[1]=2340
va[1]=1900

Code Block

title	Genericpayment start_session - Example Response

status=OK
add_paydata[payment_method_category_asset_url_descriptive]=https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg
add_paydata[client_token]=eyJhbGciOiJSUzI1NiJ9.ewogICJzZXNzaW9uX2lkIiA6ICI0N2EzNWIwOC1kNWVlLTcxYjUtOTVkMS1lYWU3NTFjNWJlZmIiLAogICJiYXNlX3VybCIgOiAiaHR0cHM6Ly9rbGFybmEtcGF5bWVudHMtZXUucGxheWdyb3VuZC5rbGFybmEuY29tIiwKICAiZGVzaWduIiA6ICJrbGFybmEiLAogICJsYW5ndWFnZSIgOiAiZW4iLAogICJwdXJjaGFzZV9jb3VudHJ5IiA6ICJERSIsCiAgInRyYWNlX2Zsb3ciIDogZmFsc2UsCiAgImVudmlyb25tZW50IiA6ICJwbGF5Z3JvdW5kIiwKICAibWVyY2hhbnRfbmFtZSIgOiAiWW91ciBidXNpbmVzcyBuYW1lIiwKICAic2Vzc2lvbl90eXBlIiA6ICJQQVlNRU5UUyIsCiAgImNsaWVudF9ldmVudF9iYXNlX3VybCIgOiAiaHR0cHM6Ly9ldnQucGxheWdyb3VuZC5rbGFybmEuY29tIiwKICAiZXhwZXJpbWVudHMiIDogWyBdCn0.gD6XVLaZeL541T1QYkGsZ01wbAYuTXyhIXcR8irG461U9w1HLugSji4_jc8LsE7cVWMVqLph_CJzCAiZNKzsC9AW6Mf88X8VdR9gV7owv3EVqEdK2K9-g-26Wu2pGE88Um2z2Iz7uUUzbhn6d4rI4CICOLsdaVXJ7MKhzPgnW-a6DM-K9JP2RLIflJKjn3wCjEtJSc_8gqj3_fv8YHaTWRkBd9pUGCBB0rUS-komFAPBdzZiCAbiw5Lsdk9dWpI2wszKeE_iPd6NuxGr4U37XtIX9Gc-uTfn21o0JUJddbiPtItmetWQSY_mruOO4WiVQxuZvxXk7XYwCCb8rrXYw
add_paydata[payment_method_category_identifier]=pay_over_time
add_paydata[session_id]=47a35b08-d5ee-71b5-95d1-eae751c5befb
add_paydata[payment_method_category_name]=Slice it.
add_paydata[payment_method_category_asset_url_standard]=https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg
workorderid=WX1A37YBGD9D11DK

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]

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Fixed value

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

update_session

add_paydata[reservation_txid]

+

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

add_paydata[session_id]

+

Identifier for the started session at Klarna

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Sample

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

068df369-13a7-4d47-a564-62f8408bb760

workorderid

+

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

Excerpt Include

	workorderid - definition
	workorderid - definition
nopanel	true

country

+

Excerpt Include

	country - definition
	country - definition
nopanel	true

amount

+

Excerpt Include

	amount - definition
	amount - definition
nopanel	true

currency

+

Excerpt Include

	currency - definition
	currency - definition
nopanel	true

financingtype

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

KIS
KIV
KDD

it[n]

+

Klarna item type

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

goods      : Goods

shipment   : Shipping charges

handling   : Handling fee

voucher    : Voucher / discount

id[n]

+

Excerpt Include

	id[n] - definition
	id[n] - definition
nopanel	true

AN..32

pr[n]

+

Excerpt Include

	pr[n] - definition
	pr[n] - definition
nopanel	true

no[n]

+

Excerpt Include

	no[n] - definition
	no[n] - definition
nopanel	true

de[n]

+

Excerpt Include

	de[n] - definition
	de[n] - definition
nopanel	true

AN..50

va[n]

+

Excerpt Include

	va[n] - definition
	va[n] - definition
nopanel	true

narrative_text

-

Excerpt Include

	narrative_text - definition
	narrative_text - definition
nopanel	true

Response "Genericpayment - update"

API parameter

Required

Comments

status

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

APPROVED

ERROR

APPROVED

workorderid

+

Excerpt Include

	workorderid - definition
	workorderid - definition
nopanel	true

ERROR

errorcode

+

Excerpt Include

	errorcode - definition
	errorcode - definition
nopanel	true

errormessage

+

Excerpt Include

	errormessage - definition
	errormessage - definition
nopanel	true

customermessage

+

Excerpt Include

	customermessage - definition
	customermessage - definition
nopanel	true

addresponsedata[reservation_txid]

Excerpt Include

	add_paydata[reservation_txid] - definition
	add_paydata[reservation_txid] - definition
nopanel	true

addresponsedata[workorderid]

Excerpt Include

	workorderid - definition
	workorderid - definition
nopanel	true

addresponsedata[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)

Anchor
cancel_authorization
cancel_authorization
Genericpayment cancel_authorization

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.

API parameter	Required	Comments
Request "Genericpayment - cancel_authorization"
add_paydata[action]	+	cancel_authorization
add_paydata[authorization_token]	+	Token of the authorization, which is to be canceled. Will be provided by Klarna's JS API

Response "Genericpayment - cancel_authorization"

API parameter

Required

Comments

status

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

APPROVED

ERROR

APPROVED

workorderid

+

Excerpt Include

	workorderid - definition
	workorderid - definition
nopanel	true

ERROR

errorcode

+

Excerpt Include

	errorcode - definition
	errorcode - definition
nopanel	true

errormessage

+

Excerpt Include

	errormessage - definition
	errormessage - definition
nopanel	true

customermessage

+

Excerpt Include

	customermessage - definition
	customermessage - definition
nopanel	true

Anchor
authorization
authorization
Preauthorization / Authorization

Request "preauthorization / authorization"

API parameter

Required

Comments

add_paydata[authorization_token]

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Sample

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

987d6543-f27b-45t5-b378-245465456780

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

String

firstname

+

Excerpt Include

	firstname - definition
	firstname - definition
nopanel	true

full address required and must match the shipping-address

lastname

+

Excerpt Include

	lastname - definition
	lastname - definition
nopanel	true

full address required and must match the shipping-address

company

-

If filled, the transaction is marked as B2B.

Excerpt Include

	company - definition
	company - definition
nopanel	true

street

+

Excerpt Include

	street - definition
	street - definition
nopanel	true

full address required and must match the shipping-address

zip

+

Excerpt Include

	zip - definition
	zip - definition
nopanel	true

full address required and must match the shipping-address

city

+

Excerpt Include

	city - definition
	city - definition
nopanel	true

full address required and must match the shipping-address

country

+

Excerpt Include

	country - definition
	country - definition
nopanel	true

full address required and must match the shipping-address

addressaddition

+

Excerpt Include

	addressaddition - definition
	addressaddition - definition
nopanel	true

mandatory for NL

gender

o

Excerpt Include

	gender - definition
	gender - definition
nopanel	true

mandatory for Austria, Germany and the Netherlands

"d" is currently not supported by Klarna

ip

+

Excerpt Include

	ip - definition
	ip - definition
nopanel	true

email

+

Excerpt Include

	email - definition
	email - definition
nopanel	true

telephonenumber

-

Excerpt Include

	telephonenumber - definition
	telephonenumber - definition
nopanel	true

birthday

o

Excerpt Include

	birthday - definition
	birthday - definition
nopanel	true

mandatory for Austria, Germany, Switzerland and the Netherlands.

shipping_firstname

-

Excerpt Include

	shipping_firstname - definition
	shipping_firstname - definition
nopanel	true

shipping_lastname

-

Excerpt Include

	shipping_lastname - definition
	shipping_lastname - definition
nopanel	true

shipping_company

-

Excerpt Include

	shipping_company - definition
	shipping_company - definition
nopanel	true

shipping_street

-

Excerpt Include

	shipping_street - definition
	shipping_street - definition
nopanel	true

shipping_zip

-

Excerpt Include

	shipping_zip - definition
	shipping_zip - definition
nopanel	true

shipping_city

-

Excerpt Include

	shipping_city - definition
	shipping_city - definition
nopanel	true

shipping_country

-

Excerpt Include

	shipping_country - definition
	shipping_country - definition
nopanel	true

personalid

o

Excerpt Include

	personalid - definition
	personalid - definition
nopanel	true

Mandatory for Denmark, Finland, Norway and Sweden

it[n]

+

Klarna item type

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

goods : Goods

shipment : Shipping charges

handling : Handling fee

voucher : Voucher / discount

id[n]

+

Excerpt Include

	id[n] - definition
	id[n] - definition
nopanel	true

pr[n]

+

Excerpt Include

	pr[n] - definition
	pr[n] - definition
nopanel	true

no[n]

+

Excerpt Include

	no[n] - definition
	no[n] - definition
nopanel	true

de[n]

+

Excerpt Include

	de[n] - definition
	de[n] - definition
nopanel	true

va[n]

+

Excerpt Include

	va[n] - definition
	va[n] - definition
nopanel	true

add_paydata[klsid]

o

Mandatory for Klarna Installment (KIS): Campaign code

Code Block

title	Authorization - Example Request

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

title	Authorization - Example Response

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

Capture

Request "capture"

API parameter

Required

Comments

txid

+

Excerpt Include

	txid - definition
	txid - definition
nopanel	true

sequencenumber

o

Excerpt Include

	sequencenumber - definition
	sequencenumber - definition
nopanel	true

capturemode

+

Parameter capturemode is mandatory to indicate whether this capture will be the last one. (Default: completed)

Excerpt Include

	capturemode - definition
	capturemode - definition
nopanel	true

settleaccount

+

Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes)

Excerpt Include

	settleaccount - definition
	settleaccount - definition
nopanel	true

amount

+

Excerpt Include

	amount - definition
	amount - definition
nopanel	true

currency

+

Excerpt Include

	settleaccount - definition
	settleaccount - definition
nopanel	true

narrative_text

-

Excerpt Include

	narrative_text - definition
	narrative_text - definition
nopanel	true

de[n]

+

Excerpt Include

	de[n] - definition
	de[n] - definition
nopanel	true

no[n]

+

Excerpt Include

	no[n] - definition
	no[n] - definition
nopanel	true

id[n]

-

Excerpt Include

	id[n] - definition
	id[n] - definition
nopanel	true

it[n]

-

Excerpt Include

	it[n] - definition
	it[n] - definition
nopanel	true

va[n]

+

Excerpt Include

	va[n] - definition
	va[n] - definition
nopanel	true

pr[n]

+

Excerpt Include

	pr[n] - definition
	pr[n] - definition
nopanel	true

add_paydata[shipping_info_shipping_company_n]

-

Name of the shipping company (as specific as possible).

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

CHAR(1..100)

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Samples

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

DHL US

DHL

add_paydata[shipping_info_shipping_method_n]

-

Shipping method.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

PickUpStore

Home

BoxReg

BoxUnreg

PickUpPoint

Own

add_paydata[shipping_info_tracking_number_n]

-

Tracking number for the shipment.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

CHAR(1..100)

add_paydata[shipping_info_tracking_uri_n]

-

URI where the customer can track their shipment.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

CHAR(1..1024)

add_paydata[shipping_info_return_shipping_company_n]

-

Name of the shipping company for the return shipment (as specific as possible).

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

CHAR(1..100)

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Samples

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

DHL US

DHL

add_paydata[shipping_info_return_tracking_uri_n]

-

URL where the customer can track the return shipment.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

CHAR(1..1024)

add_paydata[shipping_delay]

-

Delay before the order will be shipped. Use for improving the customer experience regarding payments. This field is currently not returned when reading the order.

Please note: to be able to submit values larger than 0, this has to be enabled in your merchant account. Please contact Klarna for further information.

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Format

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

INT(1..50)

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

min: 0

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

Debit / Refund

Request "Debit"

Common Parameter

Required

Short explanation

txid

+

Excerpt Include

	txid - definition
	txid - definition
nopanel	true

sequencenumber

+

Excerpt Include

	sequencenumber - definition
	sequencenumber - definition
nopanel	true

amount

+

Excerpt Include

	amount debit - definition
	amount debit - definition
nopanel	true

currency

+

Excerpt Include

	currency - definition
	currency - definition
nopanel	true

narrative_text

-

Excerpt Include

	narrative_text - definition
	narrative_text - definition
nopanel	true

use_customerdata

-

Excerpt Include

	use_customerdata - definition
	use_customerdata - definition
nopanel	true

transaction_param

-

Excerpt Include

	transaction_param - definition
	transaction_param - definition
nopanel	true

settleaccount

+

Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes)

Excerpt Include

	settleaccount - definition
	settleaccount - definition
nopanel	true

invoiceid

-

Excerpt Include

	invoiceid - definition
	invoiceid - definition
nopanel	true

invoice_deliverymode

-

Excerpt Include

	invoice_deliverymode - definition
	invoice_deliverymode - definition
nopanel	true

invoiceappendix

-

Excerpt Include

	invoiceappendix - definition
	invoiceappendix - definition
nopanel	true

invoice_deliverydate

-

Excerpt Include

	invoice_deliverydate - definition
	invoice_deliverydate - definition
nopanel	true

invoice_deliveryenddate

-

Excerpt Include

	invoice_deliveryenddate - definition
	invoice_deliveryenddate - definition
nopanel	true

it[n]

+

Excerpt Include

	it[n] - definition
	it[n] - definition
nopanel	true

id[n]

o

Excerpt Include

	id[n] - definition
	id[n] - definition
nopanel	true

pr[n]

o

Excerpt Include

	pr[n] - definition
	pr[n] - definition
nopanel	true

no[n]

o

Excerpt Include

	no[n] - definition
	no[n] - definition
nopanel	true

de[n]

o

Excerpt Include

	de[n] - definition
	de[n] - definition
nopanel	true

va[n]

-

Excerpt Include

	va[n] - definition
	va[n] - definition
nopanel	true

sd[n]

-

Excerpt Include

	sd[n] - definition
	sd[n] - definition
nopanel	true

ed[n]

-

Excerpt Include

	ed[n] - definition
	ed[n] - definition
nopanel	true

Response "Debit"

Common Parameter

Required

Comment

status

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

APPROVED

ERROR

Parameter (APPROVED)

txid

+

Excerpt Include

	txid - definition
	txid - definition
nopanel	true

settleaccount

+

Excerpt Include

	settleaccount response - definition
	settleaccount response - definition
nopanel	true

Parameter (ERROR)

errorcode

+

Excerpt Include

	errorcode - definition
	errorcode - definition
nopanel	true

errormessage

-

Excerpt Include

	errormessage - definition
	errormessage - definition
nopanel	true

customermessage

-

Excerpt Include

	customermessage - definition
	customermessage - definition
nopanel	true

Request "Refund"

API parameter

Required

Comments

txid

+

Excerpt Include

	txid - definition
	txid - definition
nopanel	true

sequencenumber

+

Excerpt Include

	sequencenumber - definition
	sequencenumber - definition
nopanel	true

amount

+

Excerpt Include

	amount refund - definition
	amount refund - definition
nopanel	true

currency

+

Excerpt Include

	currency - definition
	currency - definition
nopanel	true

narrative_text

-

Excerpt Include

	narrative_text - definition
	narrative_text - definition
nopanel	true

use_customerdata

-

Excerpt Include

	use_customerdata - definition
	use_customerdata - definition
nopanel	true

transaction_param

-

Excerpt Include

	transaction_param - definition
	transaction_param - definition
nopanel	true

invoiceid

-

Excerpt Include

	invoiceid - definition
	invoiceid - definition
nopanel	true

invoice_deliverymode

-

Excerpt Include

	invoice_deliverymode - definition
	invoice_deliverymode - definition
nopanel	true

invoiceappendix

-

Excerpt Include

	invoiceappendix - definition
	invoiceappendix - definition
nopanel	true

invoice_deliverydate

-

Excerpt Include

	invoice_deliverydate - definition
	invoice_deliverydate - definition
nopanel	true

invoice_deliveryenddate

-

Excerpt Include

	invoice_deliveryenddate - definition
	invoice_deliveryenddate - definition
nopanel	true

de[n]

+

Excerpt Include

	de[n] - definition
	de[n] - definition
nopanel	true

no[n]

+

Excerpt Include

	no[n] - definition
	no[n] - definition
nopanel	true

id[n]

+

Excerpt Include

	id[n] - definition
	id[n] - definition
nopanel	true

pr[n]

+

Excerpt Include

	pr[n] - definition
	pr[n] - definition
nopanel	true

it[n]

+

Excerpt Include

	it[n] - definition
	it[n] - definition
nopanel	true

va[n]

+

Excerpt Include

	va[n] - definition
	va[n] - definition
nopanel	true

Response "Refund"

Common Parameter

Required

Comments

status

+

Section

Layout box

cssClass	payonePermittedSymbols
floating	left

Permitted Values

Layout box

cssClass	payonePermittedSymbolsValue
floating	left

APPROVED

PENDING

ERROR

Parameter (APPROVED)

txid

+

Excerpt Include

	txid - definition
	txid - definition
nopanel	true

Parameter (PENDING)

txid

+

Excerpt Include

	txid - definition
	txid - definition
nopanel	true

Parameter (ERROR)

errorcode

+

Excerpt Include

	errorcode - definition
	errorcode - definition
nopanel	true

errormessage

+

Excerpt Include

	errormessage - definition
	errormessage - definition
nopanel	true

Voucher Handling

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 107

New Version 108

Key

Notes on This 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

AnchorwidgetwidgetKlarna Widget

Positive Response

Adjust and Try Again

Negative Response

Anchorstart_sessionstart_sessionGenericpayment start_session

Request "Generic Start Session"

Response "Genericpayment - start_session"

Anchorupdate_sessionupdate_sessionGenericpayment update_session

Request "Genericpayment - update"

Response "Genericpayment - update"

Anchorcancel_authorizationcancel_authorizationGenericpayment cancel_authorization

Request "Genericpayment - cancel_authorization"

Response "Genericpayment - cancel_authorization"

AnchorauthorizationauthorizationPreauthorization / Authorization

Request "preauthorization / authorization"

Response "preauthorization / authorization"

Capture

Request "capture"

Response "Capture"

Debit / Refund

Request "Debit"

Response "Debit"

Common Parameter

Parameter (APPROVED)

Parameter (ERROR)

Request "Refund"

Response "Refund"

Common Parameter

Parameter (APPROVED)

Parameter (PENDING)

Parameter (ERROR)

Voucher Handling

Anchor
widget
widget
Klarna Widget

Anchor
start_session
start_session
Genericpayment start_session

Anchor
update_session
update_session
Genericpayment update_session

Anchor
cancel_authorization
cancel_authorization
Genericpayment cancel_authorization

Anchor
authorization
authorization
Preauthorization / Authorization