Versions Compared

Key

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




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
yesno

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"
    • API version (question)
    • Notify-Version (question)
  • 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 Installment
financingtypeKLVKlarna 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.


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



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.




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




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[session_id]oDefaultFixed 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..50Mandatory - and can not be substituted by usage of company
lastname+
Mandatory - and can not be substituted by usage of company
street+
Mandatory - full address is required and must match the shipping-address
zip+
Mandatory - full address is required and must match the shipping-address
city+
Mandatory - full address is required and must match the shipping-address
country+
Mandatory - full address is required and must match the shipping-address
addressaddition+
Mandatory for NL
shipping-address-

Shipping-address parameters should not be used at all.

If shipping-address is used it must be the same as the invoice address !

gendero
Mandatory for Germany, Netherlands and Austria
ip+
Mandatory
email+
Mandatory
telephonenumber+
Mandatory
birthdayo
Mandatory for Germany, Netherlands and Austria
add_paydata[last_four_ssn]-
Last four digits for customer social security number.
add_paydata[organization_entity_type]-
Only relevant for B2B transactions.
personalido
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..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]o+

Mandatory for Klarna Installment (KLS): Campaign Campaigsn code

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 parameterRequiredComments
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+
amount+
currency+
financingtype+Fixed value "KLV"
it[n], id[n], pr[n], no[n], de[n], va[n]+The complete shopping cart is mandatory


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.



Anchor
authorization
authorization

Preauthorization/Authorization

Request "preauthorization / authorization"

API parameter

RequiredComments
firstname+Mandatory - and can not be substituted by usage of company
lastname+Mandatory - and can not be substituted by usage of company
street+Mandatory - full address is required and must match the shipping-address (question) Wird das sonst irgendwo abgelehnt? Wer prüft das? Können wir da vielleicht eine Note in diesem Dokument draus machen und hier nur noch "mandatory" eintragen?
zip+Mandatory - full address is required and must match the shipping-address
city+Mandatory - full address is required and must match the shipping-address
country+Mandatory - full address is required and must match the shipping-address
addressaddition+Mandatory for NL
shipping-address-

Shipping-address parameters should not be used at all.

If shipping-address is used it must be the same as the invoice address !

genderoMandatory for Germany, Netherlands and Austria
ip+Mandatory (question) wozu brauchen wir die? In der checkout API von Klarna sehe ich die nicht https://developers.klarna.com/api/#payments-api-create-a-new-order
email+Mandatory (question) wozu brauchen wir die? In der checkout API von Klarna sehe ich die nicht https://developers.klarna.com/api/#payments-api-create-a-new-order
telephonenumber+Mandatory(question) wozu brauchen wir die? In der checkout API von Klarna sehe ich die nicht https://developers.klarna.com/api/#payments-api-create-a-new-order
birthdayoMandatory for Germany, Netherlands and Austria
personalidoMandatory for Sweden, Finland, Denmark and Norway
it[n], id[n], pr[n], no[n], de[n], va[n]+The complete shopping cart must be specified.
add_paydata[klsid]o

Mandatory for Klarna Installment (KLS): Campaign code


Response "preauthorization / authorization"

API parameter

RequiredComments
add_paydata[workorderid]+

Klarna Invoice: Workorder ID, used for update calls (warning) Achtung: Hier ist das Warenkorb-Update gemeint. Das muss ebenfalls dokumentiert werden und hat nichts mit dem session update zu tun, das oben beschrieben ist

add_paydata[reservation_txid]+

Klarna Invoice: Reservation ID, used for update calls (warning) Achtung: Hier ist das Warenkorb-Update gemeint. Das muss ebenfalls dokumentiert werden und hat nichts mit dem session update zu tun, das oben beschrieben ist

Capture

Request "capture"

API parameter

RequiredComments
capturemode+Parameter capturemode is mandatory to indicate whether this capture will be the last one. (question) wenn ich das nicht mitgebe, bekomme ich keinen Fehler. Anscheinend wird also ein Wert als default genommen? Welcher?
settleaccount+Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (question) wenn ich das nicht mitgebe, bekomme ich keinen Fehler. Anscheinend wird also ein Wert als default genommen? Welcher?


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. (question) by whom, where, what?

Debit / Refund

Request "debit"

API parameter

RequiredComments
settleaccount+Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (question) wenn ich das nicht mitgebe, bekomme ich keinen Fehler. Anscheinend wird also ein Wert als default genommen? Welcher?


Table of Contents