Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.





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
typenote

B2B transactions are not supported.

API-Requests - special notes / deviations

Overview of deviations

UI Text Box
typeinfo
  • 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

fncKlarna payment types are handled as a financing payment
financingtypeKLSKlarna "Slice It" (Installment)
financingtypeKLVKlarna "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
typenote

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
bordertrue
viewerToolbartrue
fitWindowfalse
diagramNameklarna_checkout
simpleViewerfalse
width
diagramWidth1401
revision3


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

  • You need to make sure, that the customer didnddidn't accidently clicked on a Klarna payment method, because you will want to start the checkout preocess 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 witht he 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 exmpla,e example after selecting "Klarna Pay Later", the widget should look something like this:


Anchor
start_session
start_session
Genericpayment start_session

Request "generic start session"

API parameter

RequiredFormatComments
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..50First name
lastname+AN2..50Surname
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..50City
country+DefaultCountry (ISO 3166)
addressaddition+AN1..50

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

genderoDefaultf=female, m=male
ip+AN..39

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

email+AN..254Email address
telephonenumber+AN..30Telephone number
birthdayoN8Date of birth (YYYYMMDD)

shipping_firstname

-AN..50First name
shipping_lastname-AN..50Surname
shipping_company-AN2..50Company
shipping_street-AN1..50Street number and name (required: at least one character)
shipping_zip-AN2..10Postcode, format [a-zA-Z0-9_.-/]{2,10}
shipping_city-AN2..50City
shipping_country-DefaultCountry (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.
personalidoAN..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


Response "genericpayment - start_session"

API parameter

RequiredComments

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
typenote
  • 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 parameterRequired
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+DefaultCountry (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..32Product number, order number, etc.
Permitted symbols:
0-9 a-z A-Z ()[]{} +-_#/:
[n] starting with [1]; serially numbered; max [400]
pr[n]+N..10Unit gross price in cent, max. 19 999 999 99
[n] starting with [1]; serially numbered; max [400]
no[n]+N..6Quantity
[n] starting with [1]; serially numbered; max [400]
de[n]+AN..50Description
[n] starting with [1]; serially numbered; max [400]
va[n]+N..4VAT rate (% or bp) of gross price
Mandatory for payment type KLV, KLS
[n] starting with [1]; serially numbered; max [400]


Response "genericpayment - update"

API parameter

RequiredComments
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..50First name
lastname+AN2..50Surname
company-AN..50If filled, the transaction is marked as B2B.
street+AN1..50Street number and name
zip+AN2..10Postcode, format [a-zA-Z0-9_.-/]{2,10}
city+AN2..50City
country+DefaultCountry (ISO 3166)
addressaddition+AN1..50

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

genderoDefaultf=female, m=male
ip+AN..39Customer's IP-V4-address (123.123.123.123) or IP
V6-address
email+AN..254Email address
telephonenumber+AN..30Telephone number
birthdayoN8

Date of birth (YYYYMMDD)

Mandatory for Germany, Netherlands and Austria

shipping_firstname-AN..50First name
shipping_lastname-AN..50Surname
shipping_company-AN2..50Company
shipping_street-AN1..50Street number and name (required: at least one character)
shipping_zip-AN2..10

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

shipping_city-AN2..50City
shipping_country-DefaultCountry (ISO 3166)
personalidoAN..32Mandatory 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..32Product number, order number, etc.
Permitted symbols:
0-9 a-z A-Z ()[]{} +-_#/:
[n] starting with [1]; serially numbered; max [400]
pr[n]+N..10Unit gross price in cent, max. 19 999 999 99
[n] starting with [1]; serially numbered; max [400]
no[n]+N..6Quantity
[n] starting with [1]; serially numbered; max [400]
de[n]+AN..255Description
[n] starting with [1]; serially numbered; max [400]
va[n]+N..4VAT 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



Response "preauthorization / authorization"

API parameter

RequiredComments
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

Request "capture"

API parameter

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


Response "capture"

API parameter

RequiredComments
clearing_instructionnoteo
  • 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

Request "debit"

API parameter

RequiredComments
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
outlinetrue
indent2em